kurihada
a9aeb5809d
- 新增踩坑笔记: Caddy handle_path 通配符、bcrypt 兼容性、配置文件权限 - 强调推荐使用 Artalk CLI 创建管理员而非手动写哈希
228 lines
5.3 KiB
Markdown
228 lines
5.3 KiB
Markdown
# Artalk 评论系统部署
|
||
|
||
> 为 kb 接入自托管评论系统。Artalk v2.9.1：Go 后端 + SQLite，Docker 一键部署，前端 ~40KB，完全自托管无外部依赖。
|
||
|
||
---
|
||
|
||
## 架构
|
||
|
||
```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
|
||
networks:
|
||
- nginx
|
||
|
||
networks:
|
||
nginx:
|
||
external: true
|
||
```
|
||
|
||
> 注意：需要加入 `nginx` 网络以便 Caddy 能通过容器名 `artalk` 访问。
|
||
|
||
### 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` 才能生效。
|
||
|
||
### 环境变量不一定映射到配置
|
||
|
||
Docker Compose 中设置的 `ATK_SITE_DEFAULT`、`ATK_SITE_URL` 等环境变量不一定能覆盖 `artalk.yml` 中的值（取决于 Artalk 版本）。建议直接编辑 `artalk.yml` 确保生效。
|