feat: 集成 Artalk 自托管评论系统

- 新增 docs/overrides/partials/comments.html，Material 主题评论覆盖 - mkdocs.yml 添加 custom_dir: docs/overrides - 首页添加 comments: false 关闭评论 - 新增 Artalk 部署文档（Docker + Nginx 反代 + 初始化指南） - 技术 index 添加 Artalk 文档链接 - mkdocs.yml nav 添加 Artalk 评论系统入口
2026-06-04 10:54:23 +08:00
parent 00a355e1e9
commit 017daeea14
5 changed files with 214 additions and 0 deletions
@@ -0,0 +1,173 @@
+# Artalk 评论系统部署
+
+> 为 kb 接入自托管评论系统。Artalk：Go 后端 + SQLite，Docker 一键部署，前端 ~40KB，完全自托管无外部依赖。
+
+---
+
+## 架构
+
+```mermaid
+graph LR
+    Browser["浏览器"]
+    Nginx["Nginx"]
+    MkDocs["MkDocs 静态文件"]
+    Artalk["Artalk Docker<br/>:23366"]
+    SQLite[("SQLite<br/>/data")]
+
+    Browser --> Nginx
+    Nginx -->|"/"| MkDocs
+    Nginx -->|"/artalk/"| Artalk
+    Artalk --> SQLite
+```
+
+- Artalk 后端和 kb 站点部署在同一台服务器
+- Nginx 将 `/artalk/` 路径反代到 Artalk 容器
+- 前端 JS/CSS 也从同域 `/artalk/dist/` 加载，完全自托管
+
+---
+
+## 一、Docker 部署
+
+### 1.1 创建目录和 compose 文件
+
+```bash
+# 在服务器上执行
+mkdir -p /opt/artalk && cd /opt/artalk
+```
+
+`docker-compose.yml`：
+
+```yaml
+services:
+  artalk:
+    image: artalk/artalk-go
+    container_name: artalk
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:23366:23366"  # 仅本地监听，由 Nginx 反代对外
+    volumes:
+      - ./data:/data              # SQLite 数据持久化
+    environment:
+      - TZ=Asia/Shanghai
+      - ATK_LOCALE=zh-CN
+      - ATK_SITE_DEFAULT=我的知识库
+      - ATK_SITE_URL=https://<你的域名>
+      - ATK_TRUSTED_DOMAINS=https://<你的域名>
+```
+
+### 1.2 启动
+
+```bash
+docker compose up -d
+docker compose logs -f   # 查看日志确认启动成功
+```
+
+---
+
+## 二、Nginx 反向代理
+
+### 方式 A：Nginx Proxy Manager
+
+在 Proxy Manager 面板中添加一条 **Custom Location**（在你的 kb 站点 Proxy Host 里）：
+
+| 字段 | 值 |
+|------|-----|
+| Location | `/artalk/` |
+| Scheme | `http` |
+| Forward Hostname | `127.0.0.1` |
+| Forward Port | `23366` |
+
+### 方式 B：手动 Nginx 配置
+
+在 kb 站点的 `server` 块中添加：
+
+```nginx
+location /artalk/ {
+    proxy_pass http://127.0.0.1:23366/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+然后 `nginx -t && nginx -s reload`。
+
+---
+
+## 三、初始化 Artalk
+
+### 3.1 创建管理员
+
+部署完成后，访问 `https://<你的域名>/artalk/`，会看到 Artalk 的登录界面。
+
+1. 在服务器上执行命令创建管理员：
+   ```bash
+   docker exec -it artalk artalk admin
+   ```
+2. 按提示输入用户名、邮箱和密码
+3. 在网页端使用刚创建的账号登录
+
+### 3.2 验证评论功能
+
+1. 打开 kb 任意文章页面（如技术笔记）
+2. 滑到页面底部，应该看到 Artalk 评论区
+3. 发一条测试评论
+4. 确认评论正常显示
+
+---
+
+## 四、可选配置
+
+### 4.1 邮件通知
+
+在 Artalk 管理面板（设置 → 邮件）配置 SMTP，用户回复时会收到邮件通知。
+
+### 4.2 验证码
+
+管理面板 → 验证码，可开启 reCAPTCHA 或图片验证码，防止垃圾评论。
+
+### 4.3 Gravatar 头像
+
+默认启用，用户评论时根据邮箱自动显示 Gravatar 头像。
+
+### 4.4 图片上传
+
+可配置本地存储或 S3/OSS 图床，用户在评论中上传图片。
+
+---
+
+## 五、日常管理
+
+```bash
+# 查看日志
+docker logs artalk -f
+
+# 重启
+docker restart artalk
+
+# 升级
+docker compose pull
+docker compose up -d
+
+# 备份数据（SQLite 文件）
+cp /opt/artalk/data/artalk-go.db /backup/artalk-$(date +%Y%m%d).db
+```
+
+### 数据迁移
+
+Artalk 数据存储在 `/opt/artalk/data/` 目录下的 SQLite 文件中。备份只需复制这个文件。
+
+如需迁移到其他服务器，将整个 `/opt/artalk/` 目录复制过去，重新 `docker compose up -d` 即可。
+
+---
+
+## 六、MkDocs 端运作方式
+
+kb 已通过 Material 主题的 `custom_dir` 机制集成了 Artalk 前端，无需手动在每个页面添加代码。
+
+- **覆盖文件**：`docs/overrides/partials/comments.html`
+- **关闭特定页面评论**：在 `.md` 文件头部添加 `comments: false`
+- **自定义配置**：修改 `docs/overrides/partials/comments.html` 中的 `Artalk.init({...})` 参数
+
+详细参数说明见 [Artalk 前端配置文档](https://artalk.js.org/guide/frontend/config.html)。