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

Artalk 评论系统部署

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

---

技术选型

需求约束

• 自托管：不能依赖第三方 SaaS（如 Giscus、Disqus），数据在自己服务器上
• 无需 GitHub 账号：读者不应被强制要求 GitHub 登录
• 轻量：服务器资源有限，不能上 PostgreSQL 等重型依赖
• 中文友好：面向中文用户

对比了 3 款主流的自托管评论系统（数据截至 2026 年 6 月）：

	Artalk	Waline	Twikoo
后端语言	Go	Node.js	Node.js
数据库	SQLite（嵌入式）	SQLite	嵌入式文件 DB
Docker 镜像	~20MB	~150MB	~120MB
内存占用	~30MB	~100-150MB	~100MB
前端大小	~40KB	~60KB	~50KB
中文支持	一级	一级	一级
GitHub Stars	2.3k	1.8k	1.5k
管理后台	侧边栏集成	独立后台	独立后台
邮件通知	✅	✅	✅
验证码	✅ 图片验证	✅	✅
社交登录	✅ 多平台	✅	✅
图片上传	✅	✅	✅
Markdown	✅	✅	✅
多站点	✅	✅	✅

为什么选 Artalk

1. Go 后端最省资源：Artalk 是唯一用 Go 写的，Docker 镜像只有 ~20MB，运行时内存 ~30MB。Waline 和 Twikoo 都是 Node.js，内存占用 3-5 倍
2. SQLite 零维护：不需要单独跑数据库容器，数据就是一个文件，备份只需 cp 一下
3. 中文社区最强：开发者是中国人，文档完整，中文 issue 响应快
4. 前端最轻：~40KB 的 JS，对页面加载速度几乎没有影响

Walie 和 Twikoo 也都是优秀项目，功能丰富度甚至略超 Artalk。但 kb 这种低流量个人站点，省资源 + 零维护的优先级远高于功能数量，Artalk 最合适。

---

架构

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
      - ATK_SITE_DEFAULT=我的知识库
      - ATK_SITE_URL=https://note.kurihada.com
      - ATK_TRUSTED_DOMAINS=https://note.kurihada.com
    networks:
      - nginx

networks:
  nginx:
    external: true

注意：需要加入 nginx 网络以便 Caddy 能通过容器名 artalk 访问。ATK_TRUSTED_DOMAINS 限制允许跨域请求的域名，防止 CSRF。

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 才能生效。

环境变量与配置文件的关系

Artalk 2.9.x 中环境变量和 artalk.yml 均可生效。当前部署两种方式同时使用，ATK_SITE_DEFAULT、ATK_SITE_URL 在 docker-compose.yml 中设置，同时也直接写入了 artalk.yml。修改配置时建议两边保持一致，避免排查困难。