From 0b962eb2f0b02675861ef903b69c5cffdb2d014a Mon Sep 17 00:00:00 2001 From: kurihada Date: Thu, 4 Jun 2026 11:15:19 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20Artalk=20=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=96=87=E6=A1=A3=20=E2=80=94=20Caddy=20=E6=9B=BF?= =?UTF-8?q?=E4=BB=A3=20Nginx?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 架构图更新为 Caddy - 反代配置更新为 handle_path /artalk* 模式 - 更新实际部署路径和数据备份命令 - 修正 docker-compose.yml 网络配置 --- docs/技术/artalk评论系统.md | 181 ++++++++++++++++++++---------------- 1 file changed, 103 insertions(+), 78 deletions(-) diff --git a/docs/技术/artalk评论系统.md b/docs/技术/artalk评论系统.md index 1a14d22..196eaec 100644 --- a/docs/技术/artalk评论系统.md +++ b/docs/技术/artalk评论系统.md @@ -1,6 +1,6 @@ # Artalk 评论系统部署 -> 为 kb 接入自托管评论系统。Artalk：Go 后端 + SQLite，Docker 一键部署，前端 ~40KB，完全自托管无外部依赖。 +> 为 kb 接入自托管评论系统。Artalk v2.9.1：Go 后端 + SQLite，Docker 一键部署，前端 ~40KB，完全自托管无外部依赖。 --- @@ -9,33 +9,37 @@ ```mermaid graph LR Browser["浏览器"] - Nginx["Nginx"] + Caddy["Caddy"] MkDocs["MkDocs 静态文件"] Artalk["Artalk Docker
:23366"] SQLite[("SQLite
/data")] - Browser --> Nginx - Nginx -->|"/"| MkDocs - Nginx -->|"/artalk/"| Artalk + Browser --> Caddy + Caddy -->|"/"| MkDocs + Caddy -->|"/artalk* → strip prefix"| Artalk Artalk --> SQLite ``` - Artalk 后端和 kb 站点部署在同一台服务器 -- Nginx 将 `/artalk/` 路径反代到 Artalk 容器 -- 前端 JS/CSS 也从同域 `/artalk/dist/` 加载，完全自托管 +- Caddy 将 `/artalk*` 路径反代到 Artalk 容器（自动去除 `/artalk` 前缀） +- 前端 JS/CSS 同域加载 `/artalk/dist/`，完全自托管无跨域问题 --- ## 一、Docker 部署 -### 1.1 创建目录和 compose 文件 +### 1.1 实际部署位置 ```bash -# 在服务器上执行 -mkdir -p /opt/artalk && cd /opt/artalk +~/docker/artalk/ +├── docker-compose.yml +└── data/ + ├── artalk.db # SQLite 数据库 + ├── artalk.yml # 配置文件 + └── artalk.log # 日志 ``` -`docker-compose.yml`： +### 1.2 docker-compose.yml ```yaml services: @@ -43,55 +47,50 @@ services: image: artalk/artalk-go container_name: artalk restart: unless-stopped - ports: - - "127.0.0.1:23366:23366" # 仅本地监听，由 Nginx 反代对外 volumes: - - ./data:/data # SQLite 数据持久化 + - ./data:/data environment: - TZ=Asia/Shanghai - ATK_LOCALE=zh-CN - - ATK_SITE_DEFAULT=我的知识库 - - ATK_SITE_URL=https://<你的域名> - - ATK_TRUSTED_DOMAINS=https://<你的域名> + networks: + - nginx + +networks: + nginx: + external: true ``` -### 1.2 启动 +> 注意：需要加入 `nginx` 网络以便 Caddy 能通过容器名 `artalk` 访问。 + +### 1.3 启动 ```bash -docker compose up -d -docker compose logs -f # 查看日志确认启动成功 +cd ~/docker/artalk && docker compose up -d ``` --- -## 二、Nginx 反向代理 +## 二、Caddy 反向代理 -### 方式 A：Nginx Proxy Manager +Caddyfile 配置（`~/docker/caddy/Caddyfile`）： -在 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; +```caddy +note.kurihada.com { + handle_path /artalk* { + reverse_proxy artalk:23366 + } + handle { + root * /srv/mkdocs + file_server + } } ``` -然后 `nginx -t && nginx -s reload`。 +- `handle_path /artalk*`：匹配 `/artalk` 开头的路径，**自动去除 `/artalk` 前缀**后转发 +- 例如 `/artalk/dist/Artalk.js` → Artalk 收到 `/dist/Artalk.js` +- `handle { ... }` 包裹 `file_server`，保证与 `handle_path` 互斥不冲突 + +修改后重载：`docker restart caddy` --- @@ -99,41 +98,51 @@ location /artalk/ { ### 3.1 创建管理员 -部署完成后，访问 `https://<你的域名>/artalk/`，会看到 Artalk 的登录界面。 +```bash +docker exec -it artalk ./artalk admin \ + --name <用户名> \ + --email <邮箱> \ + --password <密码> +``` -1. 在服务器上执行命令创建管理员： - ```bash - docker exec -it artalk artalk admin - ``` -2. 按提示输入用户名、邮箱和密码 -3. 在网页端使用刚创建的账号登录 +或交互式：`docker exec -it artalk artalk admin` -### 3.2 验证评论功能 +### 3.2 关键配置文件 -1. 打开 kb 任意文章页面（如技术笔记） -2. 滑到页面底部，应该看到 Artalk 评论区 -3. 发一条测试评论 -4. 确认评论正常显示 +Artalk 配置文件位于 `~/docker/artalk/data/artalk.yml`，需确保以下两项正确： + +```yaml +site_default: 我的知识库 +site_url: "https://note.kurihada.com" +``` + +修改后 `docker restart artalk` 生效。 --- -## 四、可选配置 +## 四、MkDocs 端运作方式 -### 4.1 邮件通知 +kb 已通过 Material 主题的 `custom_dir` 机制集成了 Artalk 前端。 -在 Artalk 管理面板（设置 → 邮件）配置 SMTP，用户回复时会收到邮件通知。 +### 关键文件 -### 4.2 验证码 +- **覆盖模板**：`docs/overrides/partials/comments.html` — Artalk JS/CSS 引入 + 初始化 +- **CSS/JS 路径**：`/artalk/dist/Artalk.css` 和 `/artalk/dist/Artalk.js`（同域加载） +- **API 地址**：`window.location.origin + '/artalk'`（自动适配当前域名） -管理面板 → 验证码，可开启 reCAPTCHA 或图片验证码，防止垃圾评论。 +### 关闭特定页面评论 -### 4.3 Gravatar 头像 +在 `.md` 文件头部添加 frontmatter： -默认启用，用户评论时根据邮箱自动显示 Gravatar 头像。 +```yaml +--- +comments: false +--- +``` -### 4.4 图片上传 +### 深色模式 -可配置本地存储或 S3/OSS 图床，用户在评论中上传图片。 +Artalk 通过 MutationObserver 监听 Material 主题的 `data-md-color-scheme` 属性变化，自动跟随切换。 --- @@ -147,27 +156,43 @@ docker logs artalk -f docker restart artalk # 升级 -docker compose pull -docker compose up -d +cd ~/docker/artalk && docker compose pull && docker compose up -d -# 备份数据（SQLite 文件） -cp /opt/artalk/data/artalk-go.db /backup/artalk-$(date +%Y%m%d).db +# 备份数据 +cp ~/docker/artalk/data/artalk.db ~/backup/artalk-$(date +%Y%m%d).db ``` -### 数据迁移 +### 查看 Artalk 配置 -Artalk 数据存储在 `/opt/artalk/data/` 目录下的 SQLite 文件中。备份只需复制这个文件。 - -如需迁移到其他服务器，将整个 `/opt/artalk/` 目录复制过去，重新 `docker compose up -d` 即可。 +访问 `https://note.kurihada.com/artalk/api/v2/conf` 查看当前前端配置。 --- -## 六、MkDocs 端运作方式 +## 六、可选配置 -kb 已通过 Material 主题的 `custom_dir` 机制集成了 Artalk 前端，无需手动在每个页面添加代码。 +### 邮件通知 -- **覆盖文件**：`docs/overrides/partials/comments.html` -- **关闭特定页面评论**：在 `.md` 文件头部添加 `comments: false` -- **自定义配置**：修改 `docs/overrides/partials/comments.html` 中的 `Artalk.init({...})` 参数 +编辑 `~/docker/artalk/data/artalk.yml`，配置 SMTP： -详细参数说明见 [Artalk 前端配置文档](https://artalk.js.org/guide/frontend/config.html)。 +```yaml +email: + enabled: true + send_type: smtp + send_name: "{{reply_nick}}" + send_addr: noreply@example.com + smtp: + host: smtp.qq.com + port: 587 + username: example@qq.com + password: "" +``` + +然后 `docker restart artalk`。 + +### 验证码 + +默认已启用图片验证码（`captcha.captcha_type: image`），评论 3 次后触发。 + +### 社交登录 + +配置 `auth` 段可启用 GitHub/Gitea/Google 等社交账号登录，参见 [Artalk 文档](https://artalk.js.org/guide/backend/auth.html)。