feat: 添加 Caddy 反向代理配置示例及 TLS/SSL 文档

dashboard/docs/webui-tls-ssl-compose.md

@@ -0,0 +1,203 @@
+# MaiBot WebUI Compose TLS/SSL 教程
+
+本文档专门说明 Docker Compose 部署下如何通过 Caddy 为 MaiBot WebUI 提供 HTTPS。
+
+## 1. 目标结构
+
+启用后，网络结构应为：
+
+```text
+浏览器
+  -> https://maibot.example.com
+  -> Caddy 容器 :80/:443
+  -> core 容器 :8001
+  -> MaiBot WebUI
+```
+
+这意味着：
+
+1. core 不再直接对公网暴露 8001
+2. Caddy 统一接管 80 和 443
+3. Caddy 通过 Docker 网络访问 core:8001
+
+## 2. 仓库里已经补了什么
+
+本仓库已补充以下内容：
+
+1. 根目录 docker-compose.yml 中新增了默认注释的 Caddy 示例块
+2. 根目录 docker-compose.yml 中新增了默认注释的 Caddy 数据卷定义
+3. dashboard/docs/Caddyfile.docker.example 提供了 Docker Compose 专用配置模板
+4. dashboard/docs/Caddyfile.host.example 提供了非 Docker 宿主机专用配置模板
+
+## 3. 你需要手动注释或启用哪一段
+
+你要求默认保持注释状态，因此这里只明确告诉你需要操作的段落。
+
+### 3.1 需要注释掉的现有段落
+
+启用 Caddy 以后，请注释掉根目录 docker-compose.yml 中 core 服务下这一段端口映射：
+
+```yaml
+ports:
+  - "18001:8001"
+```
+
+原因很简单：
+
+1. 这段会把 WebUI 的明文 HTTP 直接暴露到宿主机
+2. 启用 HTTPS 以后，应由 Caddy 对外暴露 80 和 443
+3. 避免出现“HTTPS 入口和 HTTP 入口同时暴露”的混乱状态
+
+### 3.2 需要取消注释并启用的段落
+
+启用时你需要在根目录 docker-compose.yml 中取消注释这两部分：
+
+1. caddy 服务块
+2. volumes 里的 caddy_data 和 caddy_config
+
+## 4. 启用前需要准备什么
+
+1. 域名已经解析到你的服务器公网 IP
+2. 宿主机的 80 和 443 未被占用
+3. 防火墙和云安全组已放行 80 和 443
+4. WebUI 当前可以通过 compose 正常启动
+5. 你已经准备修改 dashboard/docs/Caddyfile.docker.example 里的域名
+
+## 5. Caddy 配置文件如何写
+
+Docker Compose 模式请使用：dashboard/docs/Caddyfile.docker.example
+
+非 Docker 宿主机模式请使用：dashboard/docs/Caddyfile.host.example
+
+最小可用配置如下：
+
+```caddyfile
+maibot.example.com {
+    reverse_proxy core:8001
+}
+```
+
+建议你至少做这两处修改：
+
+1. 把 maibot.example.com 改成你的真实域名
+2. 如果你有额外安全要求，再按需增加 header 配置
+
+## 6. compose 启用步骤
+
+### 6.1 修改 WebUI 配置
+
+先在 config/bot_config.toml 中确认：
+
+```toml
+[webui]
+mode = "production"
+secure_cookie = true
+trust_xff = true
+```
+
+trusted_proxies 的建议值取决于你的实际网络。
+
+如果 Caddy 和 core 在同一个 Docker 网络里，建议先按实际来源地址或网段填写。不要为了省事直接把范围开得过大。
+
+### 6.2 修改 Caddyfile
+
+编辑 dashboard/docs/Caddyfile.docker.example，把域名替换为真实值。
+
+### 6.3 修改 compose
+
+1. 注释掉 core 服务里对外暴露 WebUI 的 ports 段
+2. 取消注释 caddy 服务块
+3. 取消注释底部 volumes 里的 caddy_data 和 caddy_config
+
+### 6.4 启动服务
+
+```bash
+docker compose up -d
+```
+
+### 6.5 查看日志
+
+```bash
+docker compose logs -f caddy
+docker compose logs -f core
+```
+
+## 7. Let's Encrypt 申请与续期
+
+### 7.1 证书申请触发条件
+
+Caddy 容器启动后，满足以下条件时会自动申请证书：
+
+1. 域名已解析到当前服务器
+2. 80 和 443 对公网开放
+3. Caddy 能成功接收到针对该域名的请求
+
+### 7.2 自动续期说明
+
+Caddy 会自动续期。你通常不需要编写 crontab，也不需要手工执行 certbot。
+
+你只需要确保：
+
+1. caddy_data 卷被持久化
+2. 容器会长期运行
+3. 域名长期指向同一台服务器或新服务器已同步迁移数据
+4. 80 和 443 没被防火墙阻断
+
+### 7.3 续期检查建议
+
+建议定期执行：
+
+```bash
+docker compose logs --tail=200 caddy
+docker compose ps
+```
+
+重点关注：
+
+1. ACME 申请失败
+2. 证书续期失败
+3. 端口绑定失败
+4. 域名解析不一致
+
+## 8. 常见错误与排查
+
+### 8.1 证书申请失败
+
+优先检查：
+
+1. 域名是否指向服务器公网 IP
+2. 是否已经开启 CDN 代理但未正确放通验证流量
+3. 80 和 443 是否被云厂商安全组拦截
+4. 宿主机是否还有别的程序占用了 80 或 443
+
+### 8.2 登录失败
+
+优先检查：
+
+1. webui.secure_cookie 是否已启用
+2. 请求是否真正走 https:// 域名
+3. 代理是否正确传递了 X-Forwarded-Proto
+
+### 8.3 WebSocket 连接失败
+
+优先检查：
+
+1. Caddy 是否已正确反向代理到 core:8001
+2. 页面是否通过 HTTPS 打开
+3. 浏览器开发者工具里是否出现混合内容报错
+
+## 9. 迁移建议
+
+如果你目前已经在用：
+
+```yaml
+ports:
+  - "18001:8001"
+```
+
+那说明当前还是“宿主机明文 HTTP 暴露 WebUI”模式。迁移到 HTTPS 时建议：
+
+1. 先准备好域名
+2. 先改好 Caddyfile
+3. 再切换 compose 暴露方式
+4. 切换后直接以 https://域名 访问，不再继续使用 http://服务器IP:18001