fix: 修正文档中的措辞以增强可读性和一致性

2026-03-17 14:47:51 +08:00
parent 33d408d3ea
commit aa815f0c14
2 changed files with 90 additions and 34 deletions
--- a/dashboard/docs/webui-tls-ssl-compose.md
+++ b/dashboard/docs/webui-tls-ssl-compose.md
@@ -29,9 +29,9 @@
 3. dashboard/docs/Caddyfile.docker.example 提供了 Docker Compose 专用配置模板
 4. dashboard/docs/Caddyfile.host.example 提供了非 Docker 宿主机专用配置模板

-## 3. 你需要手动注释或启用哪一段
+## 3. 需要手动注释或启用的段落

-你要求默认保持注释状态，因此这里只明确告诉你需要操作的段落。
+本文档按默认保持注释状态进行说明，下面明确列出需要操作的段落。

 ### 3.1 需要注释掉的现有段落

@@ -50,18 +50,18 @@ ports:

 ### 3.2 需要取消注释并启用的段落

-启用时你需要在根目录 docker-compose.yml 中取消注释这两部分：
+启用时，需要在根目录 docker-compose.yml 中取消注释这两部分：

 1. caddy 服务块
 2. volumes 里的 caddy_data 和 caddy_config

 ## 4. 启用前需要准备什么

-1. 域名已经解析到你的服务器公网 IP
+1. 域名已经解析到服务器公网 IP
 2. 宿主机的 80 和 443 未被占用
 3. 防火墙和云安全组已放行 80 和 443
 4. WebUI 当前可以通过 compose 正常启动
-5. 你已经准备修改 dashboard/docs/Caddyfile.docker.example 里的域名
+5. 已准备修改 dashboard/docs/Caddyfile.docker.example 里的域名

 ## 5. Caddy 配置文件如何写

@@ -77,10 +77,10 @@ maibot.example.com {
 }
 ```

-建议你至少做这两处修改：
+建议至少做这两处修改：

-1. 把 maibot.example.com 改成你的真实域名
-2. 如果你有额外安全要求，再按需增加 header 配置
+1. 把 maibot.example.com 改成实际使用的域名
+2. 如果有额外安全要求，再按需增加 header 配置

 ## 6. compose 启用步骤

@@ -95,13 +95,13 @@ secure_cookie = true
 trust_xff = true
 ```

-trusted_proxies 的建议值取决于你的实际网络。
+trusted_proxies 的建议值取决于实际网络环境。

 如果 Caddy 和 core 在同一个 Docker 网络里，建议先按实际来源地址或网段填写。不要为了省事直接把范围开得过大。

 ### 6.2 修改 Caddyfile

-编辑 dashboard/docs/Caddyfile.docker.example，把域名替换为真实值。
+编辑 dashboard/docs/Caddyfile.docker.example，将域名替换为真实值。

 ### 6.3 修改 compose

@@ -134,9 +134,9 @@ Caddy 容器启动后，满足以下条件时会自动申请证书：

 ### 7.2 自动续期说明

-Caddy 会自动续期。你通常不需要编写 crontab，也不需要手工执行 certbot。
+Caddy 会自动续期，通常不需要编写 crontab，也不需要手工执行 certbot。

-你只需要确保：
+只需要确保：

 1. caddy_data 卷被持久化
 2. 容器会长期运行
@@ -188,7 +188,7 @@ docker compose ps

 ## 9. 迁移建议

-如果你目前已经在用：
+如果当前已经在使用：

 ```yaml
 ports:
--- a/dashboard/docs/webui-tls-ssl.md
+++ b/dashboard/docs/webui-tls-ssl.md
@@ -32,20 +32,20 @@ MaiBot 当前最合适的 TLS/SSL 方案是让反向代理终止 HTTPS，然后

 正式启用 HTTPS 之前，先确认下面几项：

-1. 你有一个已经解析到服务器公网 IP 的域名，例如 maibot.example.com
+1. 已准备一个已经解析到服务器公网 IP 的域名，例如 maibot.example.com
 2. 80 和 443 端口可以从公网访问
 3. 服务器没有其他程序占用 80 和 443
 4. WebUI 可以在本机正常打开，例如 http://127.0.0.1:8001

-如果你是 Docker Compose 部署，还要确认：
+如果采用 Docker Compose 部署，还要确认：

 1. 容器已经能正常启动
 2. 根目录的 docker-compose.yml 当前可以正常运行
-3. 你准备让 HTTPS 入口统一由反向代理接管
+3. HTTPS 入口将统一由反向代理接管

 ## 4. WebUI 自身配置

-无论你选 Caddy、宝塔还是 1Panel，建议先把 WebUI 配成生产模式。
+无论采用 Caddy、宝塔还是 1Panel，都建议先把 WebUI 配成生产模式。

 修改 config/bot_config.toml 里的 webui 配置段，建议值如下：

@@ -74,8 +74,8 @@ enable_paragraph_content = false

 注意：

-1. 如果你使用 Docker 内部的反向代理，trusted_proxies 不应该固定写 127.0.0.1，而应该填写反向代理容器到 MaiBot 的实际来源地址或所在网段。
-2. 如果你暂时还没切 HTTPS，不要提前把 secure_cookie = true 开起来，否则你会遇到登录 Cookie 不生效或握手异常的问题。
+1. 如果使用 Docker 内部的反向代理，trusted_proxies 不应固定写 127.0.0.1，而应填写反向代理容器到 MaiBot 的实际来源地址或所在网段。
+2. 如果尚未切换到 HTTPS，不要提前开启 secure_cookie = true，否则可能出现登录 Cookie 不生效或握手异常的问题。

 ## 5. 直接部署方式如何配置 TLS/SSL

@@ -130,7 +130,7 @@ maibot.example.com {
 }
 ```

-如果你希望明确添加安全头，可以使用增强版：
+如需显式添加安全头，可以使用增强版：

 ```caddyfile
 maibot.example.com {
@@ -147,9 +147,65 @@ maibot.example.com {
 }
 ```

-  如果你是非 Docker 直接部署，建议直接从 dashboard/docs/Caddyfile.host.example 开始修改域名并投入使用。
+非 Docker 直接部署建议直接从 dashboard/docs/Caddyfile.host.example 开始修改域名并投入使用。

-### 5.4 启动与验证
+### 5.4 HSTS 是否启用
+
+可以启用，而且当前推荐由反向代理统一下发 HSTS 响应头，而不是让 WebUI 自己在 FastAPI 层单独处理。
+
+当前仓库提供的两份 Caddy 示例都已经带了 HSTS：
+
+1. dashboard/docs/Caddyfile.host.example
+2. dashboard/docs/Caddyfile.docker.example
+
+示例配置中的这一行就是 HSTS：
+
+```caddyfile
+Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+```
+
+这行配置的含义如下：
+
+1. max-age=31536000
+   浏览器在 1 年内记住该站点只能使用 HTTPS。
+2. includeSubDomains
+   所有子域名也必须强制使用 HTTPS。
+3. preload
+   表示该域名计划提交到浏览器内置的 HSTS preload 列表。
+
+HSTS 建议按下面的节奏启用：
+
+1. 初次上线 HTTPS 时，可以先使用不带 preload 的版本。
+2. 确认主域名和所有相关子域名都长期稳定支持 HTTPS 后，再考虑是否加入 preload。
+3. 如果无法确认所有子域名都支持 HTTPS，不要轻易保留 includeSubDomains。
+
+更稳妥的起步版本如下：
+
+```caddyfile
+Strict-Transport-Security "max-age=31536000"
+```
+
+如果所有子域名都已经稳定支持 HTTPS，可以使用：
+
+```caddyfile
+Strict-Transport-Security "max-age=31536000; includeSubDomains"
+```
+
+只有在满足下面条件时，才建议使用 preload：
+
+1. 主域名始终可通过 HTTPS 访问。
+2. 所有子域名都始终可通过 HTTPS 访问。
+3. 已明确理解 preload 是长期约束，而不是临时开关。
+
+HSTS 的风险点主要有这些：
+
+1. 一旦浏览器记住该域名只能用 HTTPS，后续临时切回 HTTP 会直接失败。
+2. 如果开启 includeSubDomains，而某个子域名并没有部署 HTTPS，该子域名会被浏览器直接拦截。
+3. 如果开启 preload 并提交到浏览器列表，撤销成本会比较高，生效和移除都不是即时的。
+
+因此，本文档里的 Caddy 示例更适合作为“完整增强版示例”参考。首次部署时，建议先按实际域名情况，将 HSTS 调整成更合适的版本后再正式上线。
+
+### 5.5 启动与验证

 ```bash
 sudo caddy validate --config /etc/caddy/Caddyfile
@@ -162,9 +218,9 @@ sudo systemctl status caddy
 1. 浏览器访问 https://maibot.example.com 能正常打开登录页
 2. 登录后 Cookie 正常写入
 3. 日志页和聊天页的 WebSocket 可以正常连接
-4. 证书是 Let's Encrypt 或你指定的颁发机构签发的有效证书
+4. 证书是 Let's Encrypt 或所选颁发机构签发的有效证书

-### 5.5 直接部署方式的 Let's Encrypt 申请与续期
+### 5.6 直接部署方式的 Let's Encrypt 申请与续期

 Caddy 默认会自动处理证书签发和续期，前提如下：

@@ -172,7 +228,7 @@ Caddy 默认会自动处理证书签发和续期，前提如下：
 2. 80 和 443 可从公网访问
 3. 没有 CDN、WAF 或安全组拦截 ACME 验证请求

-Caddy 的自动续期通常无需你手工干预。你只需要：
+Caddy 的自动续期通常无需手工干预，只需确保：

 1. 保持 Caddy 常驻运行
 2. 不要阻断 80 和 443
@@ -210,7 +266,7 @@ sudo journalctl -u caddy -f
 1. 登录宝塔面板。
 2. 进入网站。
 3. 添加站点。
-4. 域名填写你的 WebUI 域名，例如 maibot.example.com。
+4. 域名填写实际使用的 WebUI 域名，例如 maibot.example.com。
 5. PHP 版本可以选纯静态或关闭运行环境，重点是站点存在即可。

 ### 6.3 反向代理配置步骤
@@ -221,7 +277,7 @@ sudo journalctl -u caddy -f
 4. 目标 URL 填写 http://127.0.0.1:8001。
 5. 发送域名通常保持目标域或原域名即可。

-如果你使用的是宝塔站点配置文件，也可以手动补这一段：
+如果使用的是宝塔站点配置文件，也可以手动补这一段：

 ```nginx
 location / {
@@ -236,7 +292,7 @@ location / {
 }
 ```

-如果你的宝塔环境没有现成的 connection_upgrade 变量，可以改成：
+如果宝塔环境没有现成的 connection_upgrade 变量，可以改成：

 ```nginx
 proxy_set_header Upgrade $http_upgrade;
@@ -248,13 +304,13 @@ proxy_set_header Connection "upgrade";
 1. 进入站点设置。
 2. 打开 SSL。
 3. 选择 Let's Encrypt。
-4. 勾选你的域名。
+4. 勾选对应域名。
 5. 申请证书。
 6. 开启强制 HTTPS。

 ### 6.5 宝塔中续期证书

-宝塔一般会自动续期，但你仍然需要检查：
+宝塔一般会自动续期，但仍然需要检查：

 1. 面板计划任务是否正常运行
 2. 80 端口是否在验证时可达
@@ -303,7 +359,7 @@ trusted_proxies = "127.0.0.1"
 5. 开启 WebSocket 支持。
 6. 保存并重载站点配置。

-如果你是在 Docker 环境里通过 1Panel 管理容器，目标地址也可以填容器服务名，例如 http://core:8001，但前提是 1Panel 管理的网关容器与 MaiBot 在同一个 Docker 网络内。
+如果是在 Docker 环境里通过 1Panel 管理容器，目标地址也可以填写容器服务名，例如 http://core:8001，但前提是 1Panel 管理的网关容器与 MaiBot 在同一个 Docker 网络内。

 ### 7.3 在 1Panel 申请 Let's Encrypt 证书

@@ -390,19 +446,19 @@ Docker 模式下请使用：dashboard/docs/Caddyfile.docker.example

 ## 10. 推荐实践

-如果你是普通 Linux 服务器部署，推荐顺序如下：
+普通 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 用户，则：
+如果采用 Docker Compose 部署，则：

 1. 使用根目录 compose 中提供的默认注释 Caddy 示例块
 2. 注释掉 core 服务里直接暴露 WebUI 的端口映射