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 最合适。

---

## 架构

```mermaid
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 实际部署位置

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

### 1.2 docker-compose.yml

```yaml
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 启动

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

---

## 二、Caddy 反向代理

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

```caddy
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 创建管理员

**推荐方式（交互式）：**

```bash
docker exec -it artalk ./artalk admin
```

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

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

### 3.2 关键配置文件

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

```yaml
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：

```yaml
---
comments: false
---
```

### 深色模式

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

---

## 五、日常管理

```bash
# 查看日志
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：

```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)。

---

## 七、踩坑笔记

### 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 创建：

```bash
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`。修改配置时建议**两边保持一致**，避免排查困难。