notebook/docs/技术/artalk评论系统.md

Artalk 评论系统部署

为 kb 接入自托管评论系统。Artalk v2.9.1：Go 后端 + SQLite，Docker 一键部署，前端 ~40KB，完全自托管无外部依赖。

---

架构

graph LR
    Browser["浏览器"]
    Caddy["Caddy"]
    MkDocs["MkDocs 静态文件"]
    Artalk["Artalk Docker<br/>:23366"]
    SQLite[("SQLite<br/>/data")]

    Browser --> Caddy
    Caddy -->|"/"| MkDocs
    Caddy -->|"/artalk* → strip prefix"| Artalk
    Artalk --> SQLite

• Artalk 后端和 kb 站点部署在同一台服务器
• Caddy 将 /artalk* 路径反代到 Artalk 容器（自动去除 /artalk 前缀）
• 前端 JS/CSS 同域加载 /artalk/dist/，完全自托管无跨域问题

---

一、Docker 部署

1.1 实际部署位置

~/docker/artalk/
├── docker-compose.yml
└── data/
    ├── artalk.db      # SQLite 数据库
    ├── artalk.yml     # 配置文件
    └── artalk.log     # 日志

1.2 docker-compose.yml

services:
  artalk:
    image: artalk/artalk-go
    container_name: artalk
    restart: unless-stopped
    volumes:
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      - ATK_LOCALE=zh-CN
    networks:
      - nginx

networks:
  nginx:
    external: true

注意：需要加入 nginx 网络以便 Caddy 能通过容器名 artalk 访问。

1.3 启动

cd ~/docker/artalk && docker compose up -d

---

二、Caddy 反向代理

Caddyfile 配置（~/docker/caddy/Caddyfile）：

note.kurihada.com {
    handle_path /artalk* {
        reverse_proxy artalk:23366
    }
    handle {
        root * /srv/mkdocs
        file_server
    }
}

• handle_path /artalk*：匹配 /artalk 开头的路径，自动去除 /artalk 前缀后转发
• 例如 /artalk/dist/Artalk.js → Artalk 收到 /dist/Artalk.js
• handle { ... } 包裹 file_server，保证与 handle_path 互斥不冲突

修改后重载：docker restart caddy

---

三、初始化 Artalk

3.1 创建管理员

推荐方式（交互式）：

docker exec -it artalk ./artalk admin

按提示输入用户名、邮箱、密码即可。Artalk 自己生成 bcrypt 哈希，不会出现兼容性问题。

⚠️ 不建议手动在 artalk.yml 中写 bcrypt 哈希。Python 等工具生成的 $2b$ 格式与 Go 的 $2a$ 不完全兼容，会导致密码验证失败。

3.2 关键配置文件

Artalk 配置文件位于 ~/docker/artalk/data/artalk.yml，需确保以下两项正确：

site_default: 我的知识库
site_url: "https://note.kurihada.com"

修改后 docker restart artalk 生效。

---

四、MkDocs 端运作方式

kb 已通过 Material 主题的 custom_dir 机制集成了 Artalk 前端。

关键文件

• 覆盖模板：docs/overrides/partials/comments.html — Artalk JS/CSS 引入 + 初始化
• CSS/JS 路径：/artalk/dist/Artalk.css 和 /artalk/dist/Artalk.js（同域加载）
• API 地址：window.location.origin + '/artalk'（自动适配当前域名）

关闭特定页面评论

在 .md 文件头部添加 frontmatter：

---
comments: false
---

深色模式

Artalk 通过 MutationObserver 监听 Material 主题的 data-md-color-scheme 属性变化，自动跟随切换。

---

五、日常管理

# 查看日志
docker logs artalk -f

# 重启
docker restart artalk

# 升级
cd ~/docker/artalk && docker compose pull && docker compose up -d

# 备份数据
cp ~/docker/artalk/data/artalk.db ~/backup/artalk-$(date +%Y%m%d).db

查看 Artalk 配置

访问 https://note.kurihada.com/artalk/api/v2/conf 查看当前前端配置。

---

六、可选配置

邮件通知

编辑 ~/docker/artalk/data/artalk.yml，配置 SMTP：

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 文档。

---

七、踩坑笔记

Caddy handle_path 必须带 * 通配符

handle_path /artalk 只匹配确切路径 /artalk，不匹配 /artalk/xxx。必须写成 handle_path /artalk*。

排查方法：docker exec caddy caddy adapt --config /etc/caddy/Caddyfile 查看生成的 JSON，看 match.path 是否包含了通配符。

管理员密码不要手动写 bcrypt 哈希

Python 生成的 $2b$ bcrypt 哈希与 Go 的 $2a$ 格式不完全兼容，直接写入 artalk.yml 可能导致密码验证失败。

正确做法是用 Artalk 自带的 CLI 创建：

docker exec -it artalk ./artalk admin

配置文件权限问题

artalk.yml 由 Docker 挂载后属主为 root，本地编辑需 sudo。修改后需 docker restart artalk 才能生效。

环境变量不一定映射到配置

Docker Compose 中设置的 ATK_SITE_DEFAULT、ATK_SITE_URL 等环境变量不一定能覆盖 artalk.yml 中的值（取决于 Artalk 版本）。建议直接编辑 artalk.yml 确保生效。