feat: integrate MinIO-backed user filesystem

2026-06-03 12:06:34 +08:00
parent a27560102b
commit ffa1249403
56 changed files with 4810 additions and 116 deletions
--- a/部署指南.md
+++ b/部署指南.md
@ -12,7 +12,7 @@

 - 浏览器能打开 `http://127.0.0.1:3081/register`
 - 注册账号后自动创建专属实例
- 浏览器跳转到 `http://<slug>.127.0.0.1.nip.io:8088`
+- 浏览器跳转到 `http://<slug>.localhost:8088`

 如果你只单独启动某个前端页面，页面可以打开，但注册、登录、创建实例这些动作不一定能通。

@ -58,14 +58,21 @@ pwd

 ## 2. 准备本机测试变量

-本机测试推荐用 `127.0.0.1.nip.io`。例如：
+本机测试推荐用 `localhost` 子域名。例如：

 ```text
-alice.127.0.0.1.nip.io -> 127.0.0.1
+alice.localhost -> 127.0.0.1 / ::1
 ```

 这样 `router-proxy` 可以按子域名区分不同实例。

+注意：
+
+- `*.localhost` 只适合在部署机器本机浏览器里测试。
+- 如果别的电脑访问 `alice.localhost`，它会指向那台电脑自己，不会指向 Beaver 服务器。
+- 局域网、服务器或正式环境必须把 `BEAVER_BASE_DOMAIN` 改成客户端能解析到 Beaver 服务器的域名，例如 `apps.example.com`。
+- 旧版文档使用过 `127.0.0.1.nip.io`。它本来应该按域名里的 IP 解析到 `127.0.0.1`，但在部分 VPN、代理、DNS 网关或内网安全设备环境下会被改写到 `198.18.0.0/15` 这类假 IP 段，导致浏览器连不上本机服务。
+
 直接执行：

 ```bash
@ -76,11 +83,17 @@ export BEAVER_PROXY_CONTAINER_NAME=beaver-router-proxy
 export BEAVER_DEPLOY_TOKEN="$(openssl rand -hex 32)"
 export BEAVER_AUTHZ_INTERNAL_TOKEN="$(openssl rand -hex 32)"

-export BEAVER_BASE_DOMAIN=127.0.0.1.nip.io
+export BEAVER_BASE_DOMAIN=localhost

 export BEAVER_AUTHZ_URL='http://beaver-authz-service:19090'
 export BEAVER_DEPLOY_URL='http://beaver-deploy-control:8090'

+export BEAVER_MINIO_ROOT_USER='beaver-minio-admin'
+export BEAVER_MINIO_ROOT_PASSWORD="$(openssl rand -hex 32)"
+export BEAVER_USER_FILES_BUCKET='beaver-user-files'
+export BEAVER_USER_FILES_MINIO_ENDPOINT='beaver-minio:9000'
+export BEAVER_USER_FILES_MAX_UPLOAD_BYTES=$((5 * 1024 * 1024 * 1024))
+
 export BEAVER_OUTLOOK_MCP_URL=''
 export BEAVER_OUTLOOK_MCP_SERVER_ID='outlook_mcp'
 ```
@ -93,12 +106,32 @@ export BEAVER_OUTLOOK_MCP_SERVER_ID='outlook_mcp'
 | `BEAVER_NET` | 所有容器共用的 Docker network |
 | `BEAVER_DEPLOY_TOKEN` | `auth-portal` / `authz-service` 调 `deploy-control` 的 token |
 | `BEAVER_AUTHZ_INTERNAL_TOKEN` | AuthZ 内部接口 token |
-| `BEAVER_BASE_DOMAIN` | 新实例的基域名 |
+| `BEAVER_BASE_DOMAIN` | 新实例的基域名；本机测试用 `localhost`，服务器部署用真实域名 |
 | `BEAVER_AUTHZ_URL` | 容器网络内访问 AuthZ 的地址 |
 | `BEAVER_DEPLOY_URL` | 容器网络内访问 deploy-control 的地址 |
+| `BEAVER_MINIO_ROOT_USER` / `BEAVER_MINIO_ROOT_PASSWORD` | 只给 provisioning 组件使用的 MinIO 管理凭据 |
+| `BEAVER_USER_FILES_BUCKET` | 用户文件系统共用 bucket，默认 `beaver-user-files` |
+| `BEAVER_USER_FILES_MINIO_ENDPOINT` | 容器网络内访问 MinIO API 的地址 |
+| `BEAVER_USER_FILES_MAX_UPLOAD_BYTES` | 用户文件系统上传上限，默认 5GB；聊天附件和 workspace 上传仍保留当前小文件限制 |
 | `BEAVER_OUTLOOK_MCP_URL` | 可选 Outlook MCP HTTP 地址 |
 | `BEAVER_OUTLOOK_MCP_SERVER_ID` | Outlook MCP server id，默认 `outlook_mcp` |

+如果接入外部正式 MinIO，不需要启动本地 `beaver-minio`。把上面的 MinIO 变量改成正式服务即可：
+
+```bash
+export BEAVER_MINIO_ROOT_USER='<minio-admin-access-key>'
+export BEAVER_MINIO_ROOT_PASSWORD='<minio-admin-secret-key>'
+export BEAVER_USER_FILES_BUCKET='beaver-user-files-formal-test'
+export BEAVER_USER_FILES_MINIO_ENDPOINT='10.6.80.98:19000'
+```
+
+注意：
+
+- `BEAVER_USER_FILES_MINIO_ENDPOINT` 是给 Python MinIO SDK 用的 S3 API endpoint，格式是 `host:port`，不要带 `http://`。
+- 操作员用 `mc` 或 `curl` 验证时才写成 `http://10.6.80.98:19000`。
+- MinIO Console 端口不是 S3 API 端口。例如 `19001` 如果返回 MinIO Console 页面，就不能填进 `USER_FILES_MINIO_ENDPOINT`。
+- 这个管理员账号只给 AuthZ provisioning 使用，用于创建共享 bucket、scoped user 和 scoped policy；不要暴露给前端或普通用户。
+
 `BEAVER_AUTHZ_URL` 和 `BEAVER_DEPLOY_URL` 必须带协议头。正确写法：

 ```text
@ -126,11 +159,37 @@ beaver-deploy-control:8090
 - `beaver-authz-service`
 - `beaver-auth-portal`

+如果改的是 `BEAVER_BASE_DOMAIN`，还要重启 `beaver-deploy-control`。这个变量只影响之后新创建的实例；已经创建过的实例 URL 已经写入 `app-instance/runtime/registry/instances.json`，不会自动改成新域名。
+
+### 非本机访问怎么配置域名
+
+如果 Beaver 部署在服务器上，而用户从其他机器访问，不要使用 `localhost`。推荐准备一个真实域名，并把通配子域名解析到服务器，例如：
+
+```text
+portal.example.com      -> Beaver 服务器
+*.apps.example.com      -> Beaver 服务器
+```
+
+然后使用：
+
+```bash
+export BEAVER_BASE_DOMAIN=apps.example.com
+```
+
+新实例 URL 会变成：
+
+```text
+http://alice.apps.example.com:8088
+```
+
+如果外层 Nginx/Caddy/负载均衡已经把 `https://*.apps.example.com` 转发到 `router-proxy`，正式环境通常还会把 `DEPLOY_PUBLIC_SCHEME` 改为 `https`，并把 `DEPLOY_PUBLIC_PORT` 改成 `443`。
+
 ## 3. 创建运行目录

 ```bash
 mkdir -p \
  "$PROJECT_ROOT/authz-service/runtime/data" \
+  "$PROJECT_ROOT/minio/runtime/data" \
  "$PROJECT_ROOT/app-instance/runtime/instances" \
  "$PROJECT_ROOT/app-instance/runtime/registry" \
  "$PROJECT_ROOT/router-proxy/runtime/conf.d"
@ -139,6 +198,7 @@ mkdir -p \
 这些目录保存：

 - AuthZ 数据
+- MinIO 对象数据
 - 实例注册表
 - 每个用户实例的配置和数据
 - `router-proxy` 生成的路由文件
@ -183,16 +243,57 @@ PROXY_HTTP_PORT=8088 \
 实例统一入口：

 ```text
-http://<slug>.127.0.0.1.nip.io:8088
+http://<slug>.localhost:8088
 ```

 示例：

 ```text
-http://alice.127.0.0.1.nip.io:8088
+http://alice.localhost:8088
 ```

-## 7. 启动 authz-service
+这里的 `localhost` 示例只表示本机测试。服务器部署时应替换为上面配置的真实基域名，例如：
+
+```text
+http://alice.apps.example.com:8088
+```
+
+## 7. 启动 MinIO
+
+MinIO 是用户文件系统的后端实现细节。用户和前端不会看到 bucket、access key 或 prefix；Beaver 只通过 `/api/user-files/*` 暴露个人智能体文件系统。
+
+如果使用外部正式 MinIO，可以跳过本节本地 MinIO 容器启动，直接进入 `authz-service` 启动步骤。
+
+```bash
+docker rm -f beaver-minio >/dev/null 2>&1 || true
+
+docker run -d \
+  --name beaver-minio \
+  --restart unless-stopped \
+  --network "$BEAVER_NET" \
+  -p 9000:9000 \
+  -p 9001:9001 \
+  -v "$PROJECT_ROOT/minio/runtime/data:/data" \
+  -e MINIO_ROOT_USER="$BEAVER_MINIO_ROOT_USER" \
+  -e MINIO_ROOT_PASSWORD="$BEAVER_MINIO_ROOT_PASSWORD" \
+  minio/minio:latest server /data --console-address ":9001"
+```
+
+用户文件采用共享 bucket + 用户 namespace：
+
+```text
+bucket: beaver-user-files
+namespace: users/{backend_id}
+example object: users/alice/uploads/report.pdf
+```
+
+每个 backend/user 会由 AuthZ provisioning 生成 scoped MinIO 凭据，policy 只允许访问自己的 `users/{backend_id}/*` prefix。
+
+用户文件路径必须使用相对的虚拟根路径，例如 `uploads/input.txt`、`outputs/report.md`、`shared/profile.json`、`tasks/<task_id>/draft.md`。`/uploads/input.txt` 这类 leading-slash absolute-style path 会被拒绝，不会再被规范化成当前用户的 `uploads/input.txt`。
+
+用户文件上传由 Beaver 后端代理到 MinIO，不暴露 bucket、prefix 或凭据。当前默认允许最大 5GB 的用户文件上传，业务上限由 app-instance 后端环境变量 `BEAVER_USER_FILES_MAX_UPLOAD_BYTES` 控制；反向代理默认 `client_max_body_size` 已提高到 5GB。MinIO 本身支持大对象和 multipart 上传，但 agent 对超大文件的读取/处理能力仍需要按具体任务另行验证。
+
+## 8. 启动 authz-service

 ```bash
 docker rm -f beaver-authz-service >/dev/null 2>&1 || true
@ -207,6 +308,13 @@ docker run -d \
  -e AUTHZ_INTERNAL_TOKEN="$BEAVER_AUTHZ_INTERNAL_TOKEN" \
  -e DEPLOY_API_BASE_URL="$BEAVER_DEPLOY_URL" \
  -e DEPLOY_API_TOKEN="$BEAVER_DEPLOY_TOKEN" \
+  -e USER_FILES_MINIO_PROVISIONING_ENABLED=1 \
+  -e USER_FILES_MINIO_ENDPOINT="$BEAVER_USER_FILES_MINIO_ENDPOINT" \
+  -e USER_FILES_MINIO_PUBLIC_ENDPOINT="$BEAVER_USER_FILES_MINIO_ENDPOINT" \
+  -e USER_FILES_MINIO_ADMIN_ACCESS_KEY="$BEAVER_MINIO_ROOT_USER" \
+  -e USER_FILES_MINIO_ADMIN_SECRET_KEY="$BEAVER_MINIO_ROOT_PASSWORD" \
+  -e USER_FILES_MINIO_BUCKET="$BEAVER_USER_FILES_BUCKET" \
+  -e USER_FILES_MINIO_SECURE=0 \
  beaver/authz-service:latest
 ```

@ -215,15 +323,16 @@ docker run -d \
 - `AUTHZ_ISSUER` 在当前部署里要写 `http://beaver-authz-service:19090`
 - 不要写 `http://127.0.0.1:19090`
 - 新创建的 `app-instance` 容器要通过 Docker network 访问 AuthZ
+- `USER_FILES_MINIO_*` 只用于 AuthZ provisioning 创建 bucket、用户、policy，并把 scoped settings 存入 AuthZ；普通用户不会接触这些配置。

 检查关键环境变量：

 ```bash
 docker inspect beaver-authz-service --format '{{range .Config.Env}}{{println .}}{{end}}' \
-  | egrep '^(AUTHZ_ISSUER|DEPLOY_API_BASE_URL)='
+  | egrep '^(AUTHZ_ISSUER|DEPLOY_API_BASE_URL|USER_FILES_MINIO_)='
 ```

-## 8. 启动 deploy-control
+## 9. 启动 deploy-control

 `deploy-control` 会挂载 Docker socket，再创建新的 `app-instance` 容器。这里最容易错的是路径挂载：

@ -252,8 +361,10 @@ docker run -d \
  -e APP_INSTANCE_IMAGE="beaver/app-instance:latest" \
  -e APP_INSTANCE_NETWORK_NAME="$BEAVER_NET" \
  -e DEFAULT_AUTHZ_BASE_URL="$BEAVER_AUTHZ_URL" \
+  -e DEFAULT_AUTHZ_INTERNAL_TOKEN="$BEAVER_AUTHZ_INTERNAL_TOKEN" \
  -e DEFAULT_AUTHZ_OUTLOOK_MCP_URL="$BEAVER_OUTLOOK_MCP_URL" \
  -e DEFAULT_OUTLOOK_MCP_SERVER_ID="$BEAVER_OUTLOOK_MCP_SERVER_ID" \
+  -e DEFAULT_USER_FILES_MAX_UPLOAD_BYTES="$BEAVER_USER_FILES_MAX_UPLOAD_BYTES" \
  -e DEPLOY_PUBLIC_SCHEME="http" \
  -e DEPLOY_PUBLIC_BASE_DOMAIN="$BEAVER_BASE_DOMAIN" \
  -e DEPLOY_PUBLIC_PORT="8088" \
@ -261,9 +372,13 @@ docker run -d \
  beaver/deploy-control:latest
 ```

+`DEPLOY_PUBLIC_BASE_DOMAIN` 来自 `BEAVER_BASE_DOMAIN`。本机测试时可以是 `localhost`；如果要让其他设备访问，必须换成它们能解析到 Beaver 服务器的真实域名。修改后需要重启 `beaver-deploy-control`，并重新创建实例或手动更新 registry 后重载 `router-proxy`。
+
 当前版本创建实例时会传 `--skip-provider-config`，也就是先不写 provider、model 或 API key。注册成功后，`auth-portal` 会进入模型配置引导页，再调用 `deploy-control /api/instances/configure-provider` 写入该实例的 `config.json` 并重启容器。

-## 9. 启动 auth-portal
+`DEFAULT_AUTHZ_INTERNAL_TOKEN` 会写入新建 app-instance 的后端 runtime env，用于 app-instance 后端读取自己的 internal MinIO settings。它不会传给前端。
+
+## 10. 启动 auth-portal

 ```bash
 docker rm -f beaver-auth-portal >/dev/null 2>&1 || true
@ -286,12 +401,13 @@ docker inspect beaver-auth-portal --format '{{range .Config.Env}}{{println .}}{{
  | egrep '^(AUTHZ_API_BASE_URL|DEPLOY_API_BASE_URL)='
 ```

-## 10. 健康检查
+## 11. 健康检查

 ```bash
 curl http://127.0.0.1:19090/healthz
 curl http://127.0.0.1:8090/healthz
 curl -I http://127.0.0.1:3081
+curl -I http://127.0.0.1:9001
 docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
 docker logs --tail=50 beaver-router-proxy
 ```
@ -299,11 +415,12 @@ docker logs --tail=50 beaver-router-proxy
 至少应该看到这些容器：

 - `beaver-authz-service`
+- `beaver-minio`
 - `beaver-deploy-control`
 - `beaver-auth-portal`
 - `beaver-router-proxy`

-## 11. 浏览器首次测试
+## 12. 浏览器首次测试

 打开：

@ -322,10 +439,140 @@ http://127.0.0.1:3081/register
 跳转目标示例：

 ```text
-http://alice.127.0.0.1.nip.io:8088
+http://alice.localhost:8088
 ```

-## 12. 确认实例已创建
+也可以运行 Playwright 冒烟测试，自动验证注册、跳过模型配置、登录交接、文件页四个根目录、上传文件，并检查 `/api/user-files/*` 不泄露 bucket、namespace 或凭据字段：
+
+```bash
+cd "$PROJECT_ROOT"
+PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/home/worker/.cache/ms-playwright/chromium-1194/chrome-linux/chrome \
+  ./scripts/smoke-auth-files.sh
+```
+
+如果要同时验证上传后的对象确实进入 MinIO 的 `users/{backend_id}/uploads/` namespace，可以加上 MinIO 校验：
+
+```bash
+BEAVER_SMOKE_VERIFY_MINIO=1 \
+BEAVER_SMOKE_MINIO_ENDPOINT=http://beaver-minio:9000 \
+BEAVER_SMOKE_MINIO_ACCESS_KEY="$BEAVER_MINIO_ROOT_USER" \
+BEAVER_SMOKE_MINIO_SECRET_KEY="$BEAVER_MINIO_ROOT_PASSWORD" \
+BEAVER_SMOKE_MINIO_BUCKET="$BEAVER_USER_FILES_BUCKET" \
+BEAVER_SMOKE_MINIO_NETWORK="$BEAVER_NET" \
+PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/home/worker/.cache/ms-playwright/chromium-1194/chrome-linux/chrome \
+  ./scripts/smoke-auth-files.sh
+```
+
+如果你的机器没有这个 Chromium 路径，可以去掉 `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`，让 Playwright 使用自己安装的浏览器。
+
+外部正式 MinIO 的重复验证流程：
+
+```bash
+cd "$PROJECT_ROOT"
+
+BEAVER_SMOKE_VERIFY_MINIO=1 \
+BEAVER_SMOKE_MINIO_ENDPOINT=http://10.6.80.98:19000 \
+BEAVER_SMOKE_MINIO_ACCESS_KEY="$BEAVER_MINIO_ROOT_USER" \
+BEAVER_SMOKE_MINIO_SECRET_KEY="$BEAVER_MINIO_ROOT_PASSWORD" \
+BEAVER_SMOKE_MINIO_BUCKET="$BEAVER_USER_FILES_BUCKET" \
+PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/home/worker/.cache/ms-playwright/chromium-1194/chrome-linux/chrome \
+  ./scripts/smoke-auth-files.sh
+```
+
+预期结果：
+
+- 新注册用户的 AuthZ MinIO settings 指向正式 endpoint 和 `users/{backend_id}` namespace。
+- 文件页只展示 `uploads`、`outputs`、`shared`、`tasks` 四个根目录。
+- `/api/user-files/*` 上传的对象出现在正式 bucket 的 `users/{backend_id}/uploads/` 下。
+- 覆盖、下载、删除都由 Beaver API 完成，前端响应不包含 bucket、namespace、access key 或 secret key。
+
+也可以运行更完整的用户文件系统验证自动化，覆盖 Files 页面四根目录 UI 删除、Logs/Subagents 等页面回归、MinIO 缺失对象验证和临时用户清理：
+
+```bash
+cd "$PROJECT_ROOT"
+
+BEAVER_VALIDATE_VERIFY_MINIO=1 \
+BEAVER_VALIDATE_MINIO_ENDPOINT=http://10.6.80.98:19000 \
+BEAVER_VALIDATE_MINIO_ACCESS_KEY="$BEAVER_MINIO_ROOT_USER" \
+BEAVER_VALIDATE_MINIO_SECRET_KEY="$BEAVER_MINIO_ROOT_PASSWORD" \
+BEAVER_VALIDATE_MINIO_BUCKET="$BEAVER_USER_FILES_BUCKET" \
+BEAVER_VALIDATE_DEPLOY_TOKEN="$BEAVER_DEPLOY_TOKEN" \
+PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/home/worker/.cache/ms-playwright/chromium-1194/chrome-linux/chrome \
+  ./scripts/validate-filesystem-automation.sh
+```
+
+### 清理测试账号和 MinIO 用户文件
+
+测试注册、Playwright smoke 或反复部署会创建 app-instance、本地实例目录、AuthZ MinIO settings，以及 MinIO 里的 scoped user、policy 和 `users/{backend_id}/` 对象。不要只手工删除 local path，否则 MinIO 里会留下无效测试资源。
+
+优先使用清理脚本。默认是 dry-run，只列出将要清理的测试账号：
+
+```bash
+cd "$PROJECT_ROOT"
+./scripts/cleanup-test-users.py --username-prefix smoke
+```
+
+确认列表无误后执行删除：
+
+```bash
+DEPLOY_CONTROL_API_TOKEN="$BEAVER_DEPLOY_TOKEN" \
+./scripts/cleanup-test-users.py \
+  --username-prefix smoke \
+  --purge-data \
+  --execute
+```
+
+这会调用 `deploy-control` 的实例删除接口，并带上：
+
+```text
+X-Purge-Data: 1
+X-Purge-User-Files: 1
+```
+
+其中 `X-Purge-Data` 删除本地实例数据，`X-Purge-User-Files` 让 deploy-control 调 AuthZ 内部接口清理 MinIO 用户文件资源。用户和普通 Files 页面不会看到 bucket、access key、secret key、policy 或 raw prefix；MinIO 仍然只是后端实现细节。
+
+如果同一个实例删除请求重复执行，deploy-control 会把本地实例已不存在报告为 `already_absent` 的成功 no-op。带 `X-Purge-User-Files: 1` 时，它仍会对同名 backend id 调用 AuthZ 的 best-effort 用户文件清理；AuthZ user-file cleanup 本身是幂等的，已不存在的 scoped user、policy、settings 或 namespace 会以 absent/no-op 状态返回。
+
+如果只想清理一个明确实例，也可以直接调用：
+
+```bash
+curl -X DELETE "http://127.0.0.1:8090/api/instances/<instance_id>" \
+  -H "Authorization: Bearer $BEAVER_DEPLOY_TOKEN" \
+  -H "X-Purge-Data: 1" \
+  -H "X-Purge-User-Files: 1"
+```
+
+如果删除过程中只有一部分成功，可以按下面的方式手工恢复。先设置 MinIO alias：
+
+```bash
+docker run --rm --network "$BEAVER_NET" --entrypoint /bin/sh minio/mc:latest -lc "
+  mc alias set beaver http://beaver-minio:9000 '$BEAVER_MINIO_ROOT_USER' '$BEAVER_MINIO_ROOT_PASSWORD'
+"
+```
+
+然后针对某个 backend id 清理对象、policy 和 user：
+
+```bash
+BACKEND_ID='<backend_id>'
+ACCESS_KEY="beaver-$BACKEND_ID"
+POLICY_NAME="beaver-user-files-$BACKEND_ID"
+
+docker run --rm --network "$BEAVER_NET" --entrypoint /bin/sh minio/mc:latest -lc "
+  mc alias set beaver http://beaver-minio:9000 '$BEAVER_MINIO_ROOT_USER' '$BEAVER_MINIO_ROOT_PASSWORD' >/dev/null &&
+  mc rm --recursive --force 'beaver/$BEAVER_USER_FILES_BUCKET/users/$BACKEND_ID/' || true &&
+  mc admin policy detach beaver '$POLICY_NAME' --user '$ACCESS_KEY' || true &&
+  mc admin user remove beaver '$ACCESS_KEY' || true &&
+  mc admin policy remove beaver '$POLICY_NAME' || true
+"
+```
+
+最后删除 AuthZ 里的 MinIO settings：
+
+```bash
+curl -X DELETE "http://127.0.0.1:19090/backends/$BACKEND_ID/settings/minio"
+```
+
+## 13. 确认实例已创建

 ```bash
 cd "$PROJECT_ROOT/app-instance"
@ -343,7 +590,7 @@ docker ps --format 'table {{.Names}}\t{{.Status}}' | grep app-instance
 - `public_url`
 - `instance_host`

-## 13. 只看 auth-portal 页面
+## 14. 只看 auth-portal 页面

 如果只想看 Portal 页面，不跑全链路：

@ -361,7 +608,7 @@ http://127.0.0.1:3081

 注意：这只能看页面。注册、登录、创建实例仍依赖 `authz-service` 和 `deploy-control`。

-## 14. 常用排错命令
+## 15. 常用排错命令

 ```bash
 docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
@ -396,7 +643,7 @@ docker inspect beaver-auth-portal --format '{{range .Config.Env}}{{println .}}{{

 它们都必须是完整 URL，不能是空字符串，也不能是裸 `host:port`。

-## 15. 常见问题
+## 16. 常见问题

 ### 注册页报 URL 缺少协议

@ -447,15 +694,30 @@ $PROJECT_ROOT/router-proxy -> $PROJECT_ROOT/router-proxy

 因为 `deploy-control` 会通过宿主机 Docker socket 再创建新容器，传给 Docker 的 bind mount 源路径必须是宿主机真实路径。

-### `nip.io` 解析失败
+### 本地域名解析失败

 检查：

 ```bash
-ping 127.0.0.1.nip.io
+getent hosts alice.localhost
 ```

-如果本地网络屏蔽了 `nip.io`，子域名测试会失败。可以临时换成本机 hosts 或正式域名。
+如果浏览器或系统没有把 `<slug>.localhost` 解析到本机，可以临时在 `/etc/hosts` 添加当前测试账号的主机名：
+
+```text
+127.0.0.1 alice.localhost
+```
+
+旧版文档使用过 `127.0.0.1.nip.io`，但部分网络会把 `nip.io` / `sslip.io` / `lvh.me` 劫持到非本机地址。例如 `127.0.0.1.nip.io` 可能被解析成 `198.18.1.27`，这通常是代理、VPN 或 DNS 网关返回的假 IP，不是 Beaver 服务地址。遇到这种情况，本机测试优先使用 `localhost` 子域名。
+
+### 服务器上不能用 `.localhost`
+
+`localhost` 是保留域名，浏览器会把它解析到“当前这台客户端机器”。所以：
+
+- 在 Beaver 服务器本机浏览器里打开 `alice.localhost`，访问的是 Beaver 服务器本机。
+- 在另一台电脑浏览器里打开 `alice.localhost`，访问的是那台电脑自己。
+
+因此远程访问、局域网访问和正式部署都不能使用 `*.localhost`。请改用真实域名或可被客户端解析到服务器的内部域名，并保证 `router-proxy` 能收到原始 `Host` 头。

 ### 端口被占用

@ -472,7 +734,7 @@ ping 127.0.0.1.nip.io
 ss -ltnp | grep -E '3081|8088|8090|19090'
 ```

-## 16. 重新部署基础容器
+## 17. 重新部署基础容器

 只重建基础四个容器：