Losita/mai-bot
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
DrSmoothl
2026-03-17 14:40:51 +08:00
parent 28afa6f2c2
commit 33d408d3ea
5 changed files with 656 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
dashboard/docs/Caddyfile.docker.example Normal file
View File

@@ -0,0 +1,12 @@
maibot.example.com {
encode zstd gzip
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
Referrer-Policy "strict-origin-when-cross-origin"
}
reverse_proxy core:8001
}

12
dashboard/docs/Caddyfile.host.example Normal file
View File

@@ -0,0 +1,12 @@
maibot.example.com {
encode zstd gzip
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
Referrer-Policy "strict-origin-when-cross-origin"
}
reverse_proxy 127.0.0.1:8001
}

203
dashboard/docs/webui-tls-ssl-compose.md Normal file
View File

@@ -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

409
dashboard/docs/webui-tls-ssl.md Normal file
View File

@@ -0,0 +1,409 @@
# MaiBot WebUI TLS/SSL 配置指南
本文档基于当前仓库实现整理，目标是让 WebUI 通过 HTTPS 提供访问能力，并保持登录、Cookie、WebSocket 和 Let's Encrypt 续期正常工作。
## 1. 先说结论
MaiBot 当前最合适的 TLS/SSL 方案是让反向代理终止 HTTPS，然后把请求转发到 WebUI 的 HTTP 服务。
推荐顺序如下：
1. Caddy 反向代理 + Let's Encrypt 自动签发与续期
2. 宝塔面板反向代理 + Let's Encrypt
3. 1Panel 反向代理 + Let's Encrypt
4. 不建议直接让 WebUI 自己监听 HTTPS，当前仓库没有现成的 WebUI 原生 TLS 配置入口
## 2. 当前项目的部署特征
当前仓库里，WebUI 的前后端是同源部署思路：
1. 后端是独立的 FastAPI WebUI 服务，默认监听 127.0.0.1:8001
2. 前端构建产物由这个 FastAPI 服务直接托管
3. 浏览器生产模式下默认按同源访问 API
4. 页面如果通过 HTTPS 打开，前端会自动把 WebSocket 协议切到 WSS
这意味着最稳妥的方式是：
1. MaiBot WebUI 继续在本机或容器内网跑 HTTP
2. 让 Caddy、宝塔 Nginx 或 1Panel OpenResty 对外暴露 443
3. 由代理把所有请求和 WebSocket 都转发到 WebUI
## 3. 配置前的准备工作
正式启用 HTTPS 之前，先确认下面几项：
1. 你有一个已经解析到服务器公网 IP 的域名，例如 maibot.example.com
2. 80 和 443 端口可以从公网访问
3. 服务器没有其他程序占用 80 和 443
4. WebUI 可以在本机正常打开，例如 http://127.0.0.1:8001
如果你是 Docker Compose 部署，还要确认：
1. 容器已经能正常启动
2. 根目录的 docker-compose.yml 当前可以正常运行
3. 你准备让 HTTPS 入口统一由反向代理接管
## 4. WebUI 自身配置
无论你选 Caddy、宝塔还是 1Panel，建议先把 WebUI 配成生产模式。
修改 config/bot_config.toml 里的 webui 配置段，建议值如下：
```toml
[webui]
enabled = true
mode = "production"
anti_crawler_mode = "loose"
allowed_ips = "127.0.0.1"
trusted_proxies = "127.0.0.1"
trust_xff = true
secure_cookie = true
enable_paragraph_content = false
```
各项的意义：
1. mode = "production"
让 WebUI 按生产环境运行，并倾向启用更严格的安全行为。
2. secure_cookie = true
让登录 Cookie 仅在 HTTPS 下传输。
3. trust_xff = true
允许从反向代理传入的 X-Forwarded-For 获取真实来源 IP。
4. trusted_proxies = "127.0.0.1"
表示只有来自本机反向代理的 X-Forwarded-For 才被信任。
注意：
1. 如果你使用 Docker 内部的反向代理，trusted_proxies 不应该固定写 127.0.0.1，而应该填写反向代理容器到 MaiBot 的实际来源地址或所在网段。
2. 如果你暂时还没切 HTTPS，不要提前把 secure_cookie = true 开起来，否则你会遇到登录 Cookie 不生效或握手异常的问题。
## 5. 直接部署方式如何配置 TLS/SSL
这里的“直接部署”指的是：
1. MaiBot 直接跑在宿主机上
2. WebUI 监听本机 127.0.0.1:8001
3. 宿主机安装 Caddy
4. 由 Caddy 负责申请证书和 HTTPS 反代
### 5.1 推荐的网络结构
```text
浏览器
-> https://maibot.example.com
-> Caddy :443
-> 127.0.0.1:8001
-> MaiBot WebUI
```
### 5.2 宿主机直装 Caddy
以 Debian 或 Ubuntu 为例，参考步骤如下：
```bash
sudo apt update
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy
```
macOS Homebrew 参考：
```bash
brew install caddy
```
### 5.3 Caddyfile 示例
仓库已提供两份可复制的示例文件，请按部署方式选择：
1. 非 Docker 宿主机部署：dashboard/docs/Caddyfile.host.example
2. Docker Compose 部署：dashboard/docs/Caddyfile.docker.example
宿主机直连部署可使用以下最简配置：
```caddyfile
maibot.example.com {
reverse_proxy 127.0.0.1:8001
}
```
如果你希望明确添加安全头，可以使用增强版：
```caddyfile
maibot.example.com {
encode zstd gzip
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
Referrer-Policy "strict-origin-when-cross-origin"
}
reverse_proxy 127.0.0.1:8001
}
```
如果你是非 Docker 直接部署，建议直接从 dashboard/docs/Caddyfile.host.example 开始修改域名并投入使用。
### 5.4 启动与验证
```bash
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl restart caddy
sudo systemctl status caddy
```
检查项：
1. 浏览器访问 https://maibot.example.com 能正常打开登录页
2. 登录后 Cookie 正常写入
3. 日志页和聊天页的 WebSocket 可以正常连接
4. 证书是 Let's Encrypt 或你指定的颁发机构签发的有效证书
### 5.5 直接部署方式的 Let's Encrypt 申请与续期
Caddy 默认会自动处理证书签发和续期，前提如下：
1. 域名已正确解析到服务器
2. 80 和 443 可从公网访问
3. 没有 CDN、WAF 或安全组拦截 ACME 验证请求
Caddy 的自动续期通常无需你手工干预。你只需要：
1. 保持 Caddy 常驻运行
2. 不要阻断 80 和 443
3. 定期关注 Caddy 日志是否存在 ACME 失败记录
常用检查命令：
```bash
sudo journalctl -u caddy -n 200 --no-pager
sudo journalctl -u caddy -f
```
如果续期失败，优先检查：
1. 域名是否仍然解析到当前服务器
2. 80 和 443 是否被防火墙、面板或云安全组拦截
3. 是否存在另一个程序抢占了 80 或 443
## 6. 宝塔面板如何配置 SSL
宝塔适合已经习惯图形化管理 Nginx 站点的部署方式。思路仍然是：由宝塔的站点反向代理到 MaiBot WebUI。
### 6.1 推荐网络结构
```text
浏览器
-> 宝塔站点 HTTPS
-> 宝塔 Nginx/OpenResty 反向代理
-> 127.0.0.1:8001
-> MaiBot WebUI
```
### 6.2 宝塔站点创建步骤
1. 登录宝塔面板。
2. 进入网站。
3. 添加站点。
4. 域名填写你的 WebUI 域名，例如 maibot.example.com。
5. PHP 版本可以选纯静态或关闭运行环境，重点是站点存在即可。
### 6.3 反向代理配置步骤
1. 进入对应站点。
2. 打开反向代理。
3. 新增反向代理。
4. 目标 URL 填写 http://127.0.0.1:8001。
5. 发送域名通常保持目标域或原域名即可。
如果你使用的是宝塔站点配置文件，也可以手动补这一段：
```nginx
location / {
proxy_pass http://127.0.0.1:8001;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
```
如果你的宝塔环境没有现成的 connection_upgrade 变量，可以改成：
```nginx
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```
### 6.4 宝塔中申请 Let's Encrypt 证书
1. 进入站点设置。
2. 打开 SSL。
3. 选择 Let's Encrypt。
4. 勾选你的域名。
5. 申请证书。
6. 开启强制 HTTPS。
### 6.5 宝塔中续期证书
宝塔一般会自动续期，但你仍然需要检查：
1. 面板计划任务是否正常运行
2. 80 端口是否在验证时可达
3. 域名解析是否未被改动
建议定期查看：
1. 宝塔站点 SSL 到期时间
2. 宝塔计划任务执行日志
3. 站点错误日志和 Nginx 错误日志
### 6.6 宝塔模式下 WebUI 配置建议
建议保持：
```toml
[webui]
mode = "production"
secure_cookie = true
trust_xff = true
trusted_proxies = "127.0.0.1"
```
如果宝塔和 MaiBot 不在同一台机器上，trusted_proxies 需要换成宝塔所在服务器到 MaiBot 的来源地址。
## 7. 1Panel 如何配置 SSL
1Panel 的逻辑和宝塔类似，本质上也是由面板管理的网关或站点反向代理到 MaiBot WebUI。
### 7.1 推荐网络结构
```text
浏览器
-> 1Panel 网站/反向代理 HTTPS
-> OpenResty/Nginx 反向代理
-> 127.0.0.1:8001 或 core:8001
-> MaiBot WebUI
```
### 7.2 1Panel 配置步骤
1. 登录 1Panel。
2. 打开网站或反向代理管理。
3. 新建网站，域名填 maibot.example.com。
4. 添加反向代理规则，目标地址指向 http://127.0.0.1:8001。
5. 开启 WebSocket 支持。
6. 保存并重载站点配置。
如果你是在 Docker 环境里通过 1Panel 管理容器，目标地址也可以填容器服务名，例如 http://core:8001，但前提是 1Panel 管理的网关容器与 MaiBot 在同一个 Docker 网络内。
### 7.3 在 1Panel 申请 Let's Encrypt 证书
1. 打开证书管理。
2. 选择 Let's Encrypt。
3. 绑定域名。
4. 选择 HTTP-01 或面板默认验证方式。
5. 完成签发后，把证书绑定到对应网站。
6. 启用 HTTPS。
### 7.4 1Panel 中续期证书
1Panel 通常会自动续期，但需要确认：
1. 自动续期开关处于启用状态
2. 面板的任务调度正常
3. 80 和 443 端口验证时不被拦截
4. 域名始终指向正确服务器
### 7.5 1Panel 模式下的反代头
请确认面板生成的配置会向后端传递：
1. Host
2. X-Real-IP
3. X-Forwarded-For
4. X-Forwarded-Proto
5. Upgrade
6. Connection
缺少 X-Forwarded-Proto 时，WebUI 可能误判为 HTTP，进而影响 secure cookie 与登录行为。
## 8. Docker Compose 下如何配置 TLS/SSL
根目录 docker-compose.yml 已补充默认注释的 Caddy 示例块，用于容器化部署时启用 HTTPS。
Docker 模式下请使用：dashboard/docs/Caddyfile.docker.example
非 Docker 宿主机模式下请使用：dashboard/docs/Caddyfile.host.example
详细步骤请看另一份专项文档：dashboard/docs/webui-tls-ssl-compose.md
这里只先给结论：
1. 启用 Caddy 反向代理时，不应再把 core 的 8001 直接映射到公网
2. 应由 Caddy 容器暴露 80 和 443
3. Caddy 通过容器网络访问 core:8001
## 9. 常见问题
### 9.1 开了 HTTPS 后无法登录
优先检查：
1. webui.secure_cookie 是否在 HTTPS 环境下开启
2. 代理是否正确传递 X-Forwarded-Proto
3. 浏览器访问的是否确实是 https:// 域名而不是 http:// IP
4. Cookie 是否被浏览器策略、扩展或跨站配置拦截
### 9.2 页面能打开，但日志页或聊天页 WebSocket 失败
优先检查：
1. 代理是否支持 WebSocket Upgrade
2. 是否使用了 HTTPS 页面去连接 ws:// 明文地址
3. Caddy、Nginx、宝塔、1Panel 是否有单独的 WebSocket 开关或升级头配置
### 9.3 Let's Encrypt 申请失败
优先检查：
1. 域名解析是否正确
2. 80 端口是否可访问
3. 是否开启了 CDN 代理但没有正确放通验证流量
4. 面板或防火墙是否拦截 ACME 请求
### 9.4 是否能直接用 IP 申请 Let's Encrypt
不能。Let's Encrypt 只为域名签发公开可信证书，不为裸 IP 签发。
### 9.5 内网环境如何测试 HTTPS
可以使用 Caddy 的 tls internal 进行测试，但客户端必须手工信任内部 CA 根证书。正式对外服务仍建议使用有效公网域名和 Let's Encrypt。
## 10. 推荐实践
如果你是普通 Linux 服务器部署，推荐顺序如下：
1. 宿主机直装 Caddy
2. WebUI 绑定 127.0.0.1:8001
3. 域名指向服务器
4. 用 Caddy 反代并自动管理 Let's Encrypt
如果你已经使用面板管理服务器，则：
1. 宝塔用户直接用宝塔反向代理和 Let's Encrypt
2. 1Panel 用户直接用 1Panel 网站或网关反代和证书管理
如果你是 Docker Compose 用户，则：
1. 使用根目录 compose 中提供的默认注释 Caddy 示例块
2. 注释掉 core 服务里直接暴露 WebUI 的端口映射
3. 由 Caddy 统一对外暴露 80 和 443

20
docker-compose.yml
View File

@@ -44,6 +44,24 @@ services:
restart: always
networks:
- maim_bot
# 启用 HTTPS 时，建议注释掉 core 服务中的 "18001:8001" 端口映射，
# 然后取消注释此 Caddy 反向代理示例块，并按 dashboard/docs/Caddyfile.docker.example 修改域名。
# caddy:
# image: caddy:2
# container_name: maibot-caddy
# restart: always
# ports:
# - "80:80"
# - "443:443"
# volumes:
# - ./dashboard/docs/Caddyfile.docker.example:/etc/caddy/Caddyfile:ro
# - caddy_data:/data
# - caddy_config:/config
# depends_on:
# - core
# networks:
# - maim_bot
napcat:
environment:
- NAPCAT_UID=1000
@@ -89,6 +107,8 @@ services:
# volumes: # 若需要持久化Python包时启用
# site-packages:
# caddy_data:
# caddy_config:
networks:
maim_bot:
driver: bridge