docs(auth): add social login feature (#854)

ArtalkJS · May 3, 2024 · 2d0bd3d · 2d0bd3d
1 parent e5ea973
commit 2d0bd3d
Show file tree

Hide file tree

Showing 14 changed files with 107 additions and 10 deletions.
diff --git a/docs/docs/.vitepress/config.ts b/docs/docs/.vitepress/config.ts
@@ -100,6 +100,7 @@ export default defineConfig({
             { text: '侧边栏', link: '/guide/frontend/sidebar.md' },
             { text: '邮件通知', link: '/guide/backend/email.md' },
             { text: '多元推送', link: '/guide/backend/admin_notify.md' },
+            { text: '社交登录', link: '/guide/frontend/auth.md' },
             { text: '评论审核', link: '/guide/backend/moderator.md' },
             { text: '验证码', link: '/guide/backend/captcha.md' },
             { text: '图片上传', link: '/guide/backend/img-upload.md' },

diff --git a/docs/docs/guide/backend/img-upload.md b/docs/docs/guide/backend/img-upload.md
@@ -6,7 +6,7 @@ Artalk 提供图片上传功能，支持限制图片大小、上传频率等，
 
 ## 配置文件
 
-完整的 `img-upload` 配置如下：
+完整的 `img_upload` 配置如下：
 
 ```yaml
 # 图片上传

diff --git a/docs/docs/guide/deploy.md b/docs/docs/guide/deploy.md
@@ -39,13 +39,13 @@ docker exec -it artalk artalk admin
 <!-- Artalk -->
 <div id="Comments"></div>
 <script>
-  Artalk.init({
+Artalk.init({
   el:        '#Comments',                // 绑定元素的 Selector
   pageKey:   '/post/1',                  // 固定链接 (留空自动获取)
   pageTitle: '关于引入 Artalk 的这档子事',  // 页面标题 (留空自动获取)
   server:    'http://your_domain:8080',  // 后端地址
   site:      'Artalk 的博客',             // 你的站点名
-  })
+})
 </script>
 ```
 <!-- prettier-ignore-end -->

diff --git a/docs/docs/guide/frontend/auth.md b/docs/docs/guide/frontend/auth.md
@@ -0,0 +1,75 @@
+# 社交登录
+
+Artalk 默认只需填写昵称和邮箱即可发表评论，无需验证邮箱。
+
+但有时候，我们希望用户能够使用社交账号登录，以减少用户填写信息的时间，或者提高用户信息的真实性，可以通过启用社交登录来实现这一目的。
+
+社交登录目前支持以下多种方式：
+
+| 登录方式 | 接入文档 | 登录方式 | 接入文档 | 登录方式 | 接入文档 |
+| --- | --- | --- | --- | --- | --- |
+| Google | [查看](https://developers.google.com/identity/protocols/oauth2) | Microsoft | [查看](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow) | Apple | [查看](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/configuring_your_webpage_for_sign_in_with_apple) |
+| Facebook | [查看](https://developers.facebook.com/docs/facebook-login/) | Twitter | [查看](https://developer.twitter.com/en/docs/basics/authentication/overview) | Discord | [查看](https://discord.com/developers/docs/topics/oauth2) |
+| Slack | [查看](https://api.slack.com/authentication/oauth-v2) | Github | [查看](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/) | Tiktok | [查看](https://developers.tiktok.com/doc/login) |
+| Steam | [查看](https://partner.steamgames.com/doc/webapi_overview/auth) | WeChat | [查看](https://developers.weixin.qq.com/doc/oplatform/Website_App/WeChat_Login/Wechat_Login.html) | Line | [查看](https://developers.line.biz/en/docs/line-login/integrate-line-login/) |
+| GitLab | [查看](https://docs.gitlab.com/ee/api/oauth2.html) | Gitea | [查看](https://docs.gitea.io/en-us/oauth2-provider/) | Mastodon | [查看](https://docs.joinmastodon.org/api/authentication/) |
+| Patreon | [查看](https://docs.patreon.com/#oauth) | Auth0 | [查看](https://auth0.com/docs/connections/social/) | 邮箱密码 | [查看](#邮箱密码登录) |
+
+开启社交登录功能仅需在 Artalk 控制中心的设置页面找到「社交登录」选项，首先启用该功能，然后填写对应的配置信息即可。
+
+## 邮箱密码登录
+
+![邮箱登录](../../images/auth/email_login.png)
+
+启用邮箱密码登录后，评论框顶部的昵称邮箱输入框将被隐藏，发送按钮将显示为登录按钮。用户点击登录按钮后，将会弹出一个登录框，用户可以输入邮箱和密码登录，登录成功后即可发表评论。并且，用户发表的评论将展示「邮箱已验证」的标识。
+
+<img src="../../images/auth/email_verified.png" width="550" alt="邮箱已验证标识">
+
+用户可以通过邮箱注册账号，Artalk 将向用户邮箱发送一封带有验证码的邮件。验证码有效期为 10 分钟，验证码发送频率限制为 1 分钟一次。
+
+![邮箱注册](../../images/auth/email_register.png)
+
+支持自定义验证码邮件模板和邮件标题，可在 Artalk 控制中心的设置页面的社交登录找到「邮箱验证邮件标题」、「邮箱验证邮件模板」选项进行设置。在配置文件中，可以通过 `auth.email.verify_subject` 和 `auth.email.verify_tpl` 进行设置：
+
+```yaml
+auth:
+  enabled: true
+  email:
+    enabled: true
+    verify_subject: "您的验证码是 - {{code}}"
+    verify_tpl: default
+```
+
+默认模版如下：
+
+```html
+您的验证码是：{{code}}。请使用它来验证您的电子邮件并登录到 Artalk。如果您没有请求此操作，请忽略此消息。
+```
+
+![跳过登录](../../images/auth/login_skip.png)
+
+启用邮箱密码登录功能后，仍然可跳过邮箱验证：登录弹窗底部显示 “跳过，不验证” 按钮，点击后评论框顶部恢复为显示原有的昵称、邮箱、网址三个输入框。在设置中勾选「允许匿名评论」可以更改。
+
+## 账号合并工具
+
+登录后如果检测到相同的邮箱下有多个不同用户名的账号，将会弹出账号合并工具，用户可以选择保留其中一个用户名，该邮箱下的所有评论等数据合并到保留的账号下。原有的账号将被删除，评论显示的用户名将会变更为保留的用户名。
+
+![账号合并工具](../../images/auth/merge_accounts.png)
+
+## 多种登录方式
+
+Artalk 支持同时启用多种登录方式，用户可以选择任意一种方式登录。
+
+![多种登录方式](../../images/auth/multi_login.png)
+
+如果只启用了唯一一种登录，例如 GitHub 登录，将直接弹出 GitHub 的授权登录页面。
+
+![GitHub 授权弹窗](../../images/auth/github_login.png)
+
+接入 GitHub 登录可参考文档：[关于创建 GitHub 应用](https://docs.github.com/zh/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)，得到 Client ID 和 Client Secret 后，填写到 Artalk 控制中心的设置页面的社交登录中的「GitHub」选项中即可。
+
+## 插件开发
+
+Artalk 的社交登录功能是通过独立的插件实现并采用 Solid.js 开发，代码可在 [@ArtalkJS/Artalk:ui/plugin-auth](https://github.com/ArtalkJS/Artalk/tree/master/ui/plugin-auth) 找到。
+
+在控制中心启用社交登录功能后，将自动在前端加载该插件。
diff --git a/docs/docs/guide/intro.md b/docs/docs/guide/intro.md
@@ -18,8 +18,9 @@
 
   - Markdown 语法 + 代码高亮
   - [通知中心](./frontend/sidebar.md) - 站内：侧边栏 + 红点标记
-  - [多形式推送](./backend/admin_notify.md) - 站外：邮件、TG、钉钉、飞书 + 异步执行
+  - [多元推送](./backend/admin_notify.md) - 站外：邮件、TG、钉钉、飞书 + 异步执行
   - [评论审核](./backend/moderator.md)：折叠 / 反垃圾 / 频率限制 / 滑动验证
+  - [社交登录](./frontend/auth.md)：邮箱密码、GitHub、Google 等多种登录方式
   - [多站点](./backend/multi-site.md)：共用同一个后端程序，多站点集中化管理
   - [表情包](./frontend/emoticons.md)：支持 OwO 格式 + 动态加载
   - [Artrans](./transfer.md)：评论数据快速迁移 (导入 / 导出) 工具

diff --git a/docs/docs/images/auth/email_login.png b/docs/docs/images/auth/email_login.png
diff --git a/docs/docs/images/auth/email_register.png b/docs/docs/images/auth/email_register.png
diff --git a/docs/docs/images/auth/email_verified.png b/docs/docs/images/auth/email_verified.png
diff --git a/docs/docs/images/auth/github_login.png b/docs/docs/images/auth/github_login.png
diff --git a/docs/docs/images/auth/login_skip.png b/docs/docs/images/auth/login_skip.png
diff --git a/docs/docs/images/auth/merge_accounts.png b/docs/docs/images/auth/merge_accounts.png
diff --git a/docs/docs/images/auth/multi_login.png b/docs/docs/images/auth/multi_login.png
diff --git a/docs/landing/src/components/Features/FullFeatureList.tsx b/docs/landing/src/components/Features/FullFeatureList.tsx
@@ -1,9 +1,10 @@
 import React from 'react'
-import { TbLayoutSidebarRightExpandFilled, TbMailFilled, TbEyeFilled, TbTransformFilled, TbLocationFilled, TbCardsFilled, TbPhotoSearch, TbMath, TbPlug, TbLanguage, TbTerminal, TbApi } from 'react-icons/tb'
+import { TbLayoutSidebarRightExpandFilled, TbMailFilled, TbEyeFilled, TbTransformFilled, TbLocationFilled, TbCardsFilled, TbPhotoSearch, TbMath, TbPlug, TbLanguage, TbTerminal, TbApi, TbSocial } from 'react-icons/tb'
 import { BiSolidNotification, BiSolidBadgeCheck } from 'react-icons/bi'
-import { RiRobot2Fill, RiUpload2Fill } from 'react-icons/ri'
+import { RiLoader4Fill, RiRobot2Fill, RiUpload2Fill } from 'react-icons/ri'
 import { BsFillShieldLockFill } from 'react-icons/bs'
 import { PiSmileyWinkBold } from 'react-icons/pi'
+import { GrUpgrade } from 'react-icons/gr'
 
 interface FuncItem {
   icon: React.ReactNode
@@ -43,6 +44,12 @@ const FuncList: FuncItem[] = [
     desc: '内容检测、垃圾拦截',
     link: 'https://artalk.js.org/guide/backend/moderator.html'
   },
+  {
+    icon: <TbSocial />,
+    name: '社交登录',
+    desc: 'GitHub 等多种登录方式',
+    link: 'https://artalk.js.org/guide/frontend/auth.html'
+  },
   {
     icon: <RiUpload2Fill />,
     name: '图片上传',
@@ -80,17 +87,23 @@ const FuncList: FuncItem[] = [
     link: 'https://artalk.js.org/guide/transfer.html'
   },
   {
-    icon: <TbLocationFilled />,
-    name: 'IP 属地',
-    desc: '用户 IP 属地展示',
-    link: 'https://artalk.js.org/guide/frontend/ip-region.html'
+    icon: <RiLoader4Fill />,
+    name: '图片懒加载',
+    desc: '延迟加载图片，优化体验',
+    link: 'https://artalk.js.org/guide/frontend/img-lazy-load.html'
   },
   {
     icon: <TbPhotoSearch />,
     name: '图片灯箱',
     desc: '快速集成图片灯箱',
     link: 'https://artalk.js.org/guide/frontend/lightbox.html'
   },
+  {
+    icon: <TbLocationFilled />,
+    name: 'IP 属地',
+    desc: '用户 IP 属地展示',
+    link: 'https://artalk.js.org/guide/frontend/ip-region.html'
+  },
   {
     icon: <TbMath />,
     name: 'Latex',
@@ -121,6 +134,12 @@ const FuncList: FuncItem[] = [
     desc: '提供 OpenAPI 格式文档',
     link: 'https://artalk.js.org/develop/'
   },
+  {
+    icon: <GrUpgrade />,
+    name: '程序升级',
+    desc: '版本检测，一键升级',
+    link: 'https://artalk.js.org/guide/backend/update.html'
+  }
 ]
 
 export const FullFeatureList: React.FC = () => {

diff --git a/docs/landing/src/components/Features/FuncFeature.tsx b/docs/landing/src/components/Features/FuncFeature.tsx
@@ -7,6 +7,7 @@ import { Reveal } from '../Reveal'
 import { FaArrowRight } from 'react-icons/fa'
 
 const FuncGrps: {name: string, items: string[], link?: string}[] = [
+  { name: '社交登录', items: ['Github', 'GitLab', 'Twitter', 'Facebook', 'Mastodon', 'Google', 'Microsoft', 'Apple', 'Discord', 'Slack', 'Tiktok', 'Steam'], link: 'https://artalk.js.org/guide/frontend/auth.html' },
   { name: '邮箱发送', items: ['SMTP', '阿里云邮件', 'sendmail'], link: 'https://artalk.js.org/guide/backend/email.html' },
   { name: '验证码', items: ['Turnstile', 'reCAPTCHA', 'hCaptcha', '极验'], link: 'https://artalk.js.org/guide/backend/captcha.html' },
   { name: '消息推送', items: ['Telegram', '飞书', '钉钉', 'Bark', 'WebHook', 'Slack', 'LINE'], link: 'https://artalk.js.org/guide/backend/admin_notify.html' },