From 017daeea14c4939f985d8b71680948351f365a15 Mon Sep 17 00:00:00 2001 From: kurihada Date: Thu, 4 Jun 2026 10:54:23 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E9=9B=86=E6=88=90=20Artalk=20=E8=87=AA?= =?UTF-8?q?=E6=89=98=E7=AE=A1=E8=AF=84=E8=AE=BA=E7=B3=BB=E7=BB=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 docs/overrides/partials/comments.html，Material 主题评论覆盖 - mkdocs.yml 添加 custom_dir: docs/overrides - 首页添加 comments: false 关闭评论 - 新增 Artalk 部署文档（Docker + Nginx 反代 + 初始化指南） - 技术 index 添加 Artalk 文档链接 - mkdocs.yml nav 添加 Artalk 评论系统入口 --- docs/index.md | 4 + docs/overrides/partials/comments.html | 34 +++++ docs/技术/artalk评论系统.md | 173 ++++++++++++++++++++++++++ docs/技术/index.md | 1 + mkdocs.yml | 2 + 5 files changed, 214 insertions(+) create mode 100644 docs/overrides/partials/comments.html create mode 100644 docs/技术/artalk评论系统.md diff --git a/docs/index.md b/docs/index.md index efcb2a4..7357c65 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,7 @@ +--- +comments: false +--- + # 🏠 我的知识库 欢迎！这里是我（kurihada）的个人知识内容存储。 diff --git a/docs/overrides/partials/comments.html b/docs/overrides/partials/comments.html new file mode 100644 index 0000000..ad16df2 --- /dev/null +++ b/docs/overrides/partials/comments.html @@ -0,0 +1,34 @@ +{#- + Artalk 评论系统集成 + 通过 Material 主题的 comments 块覆盖实现 + 如需关闭某页面的评论，在页面 frontmatter 中设置 comments: false +-#} +{% if page.meta.comments is not defined or page.meta.comments %} +
+ + + +{% endif %} diff --git a/docs/技术/artalk评论系统.md b/docs/技术/artalk评论系统.md new file mode 100644 index 0000000..1a14d22 --- /dev/null +++ b/docs/技术/artalk评论系统.md @@ -0,0 +1,173 @@ +# Artalk 评论系统部署 + +> 为 kb 接入自托管评论系统。Artalk：Go 后端 + SQLite，Docker 一键部署，前端 ~40KB，完全自托管无外部依赖。 + +--- + +## 架构 + +```mermaid +graph LR + Browser["浏览器"] + Nginx["Nginx"] + MkDocs["MkDocs 静态文件"] + Artalk["Artalk Docker
:23366"] + SQLite[("SQLite
/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)。 diff --git a/docs/技术/index.md b/docs/技术/index.md index f57421b..510195b 100644 --- a/docs/技术/index.md +++ b/docs/技术/index.md @@ -32,3 +32,4 @@ ## 📝 技术笔记 - [旁路由 + 去广告 部署](旁路由部署.md) — sing-box + AdGuard Home 旁路由架构、配置路径、已知问题 +- [Artalk 评论系统](artalk评论系统.md) — 自托管评论系统，Docker 部署 + MkDocs 集成 diff --git a/mkdocs.yml b/mkdocs.yml index 3c5b0ef..24e44b0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,6 +29,7 @@ theme: - search.suggest # 搜索建议 - search.highlight # 搜索高亮 - content.code.copy # 代码块复制按钮 + custom_dir: docs/overrides # 自定义模板覆盖（评论系统等） markdown_extensions: - admonition # 提示框 !!! note @@ -67,6 +68,7 @@ nav: - 技术: - 技术/index.md - 旁路由部署: 技术/旁路由部署.md + - Artalk 评论系统: 技术/artalk评论系统.md - 旁路由使用: - Linux: 技术/旁路由使用/Linux.md - Windows: 技术/旁路由使用/Windows.md