docs: 完善 Artalk 部署文档 — 添加踩坑笔记和管理员创建说明

- 新增踩坑笔记: Caddy handle_path 通配符、bcrypt 兼容性、配置文件权限
- 强调推荐使用 Artalk CLI 创建管理员而非手动写哈希

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

@@ -98,14 +98,15 @@ note.kurihada.com {
 
 ### 3.1 创建管理员
 
+**推荐方式（交互式）：**
+
 ```bash
-docker exec -it artalk ./artalk admin \
+docker exec -it artalk ./artalk admin
-  --name <用户名> \
-  --email <邮箱> \
-  --password <密码>
 ```
 
-或交互式：`docker exec -it artalk artalk admin`
+按提示输入用户名、邮箱、密码即可。Artalk 自己生成 bcrypt 哈希，不会出现兼容性问题。
+
+> ⚠️ 不建议手动在 `artalk.yml` 中写 bcrypt 哈希。Python 等工具生成的 `$2b$` 格式与 Go 的 `$2a$` 不完全兼容，会导致密码验证失败。
 
 ### 3.2 关键配置文件
 
@@ -196,3 +197,31 @@ email:
 ### 社交登录
 
 配置 `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` 确保生效。