From d30365d4e40a6683b6355996141a6fe433d056bd Mon Sep 17 00:00:00 2001 From: ila Date: Tue, 25 Aug 2026 15:12:45 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=98=8E=E7=A1=AE=20Portal=20YAML=20?= =?UTF-8?q?=E9=85=8D=E7=BD=AE=E4=BC=98=E5=85=88=E7=BA=A7=20(#56)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/04-local-development-and-verification.md | 17 +++++++++-------- docs/10-deployment-and-operations.md | 18 +++++++++--------- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index ac919fb..0efdf00 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Local-Development-and-Verification.- -wiki_revision: 660d4bc4e857a92c6cf6606d2af95d1b5f2f6d04 -synchronized_at: 2026-08-25T07:00:57Z +wiki_revision: 15b778ecf22e191fb196ca94f73141b385a1c941 +synchronized_at: 2026-08-25T07:09:22Z # 本地开发与验证 @@ -326,12 +326,13 @@ git diff --check 内嵌 worker 的运行参数： -| 变量 | 非生产默认 | 生产要求 | -|---|---:|---| -| `CHORUS_WORKER_LEASE_SECONDS` | 60 | 必须显式设置，且大于 HTTP 超时 + 5 秒 | -| `CHORUS_WORKER_POLL_MILLISECONDS` | 250 | 必须显式设置 | -| `CHORUS_PROVIDER_HTTP_TIMEOUT_SECONDS` | 45 | 必须显式设置 | -| `CHORUS_PROVIDER_MAX_RESPONSE_BYTES` | 33554432 | 必须显式设置 | +| YAML 字段 | 环境覆盖变量 | 示例值与约束 | +|---|---|---| +| `worker.lease_seconds` | `CHORUS_WORKER_LEASE_SECONDS` | 60；必须大于 HTTP 超时 + 5 秒 | +| `worker.poll_milliseconds` | `CHORUS_WORKER_POLL_MILLISECONDS` | 250；正整数 | +| `provider.http_timeout_seconds` | `CHORUS_PROVIDER_HTTP_TIMEOUT_SECONDS` | 45；正整数 | +| `provider.max_response_bytes` | `CHORUS_PROVIDER_MAX_RESPONSE_BYTES` | 33554432；正整数 | +| `provider.allowed_ports` | `CHORUS_PROVIDER_ALLOWED_PORTS` | 默认示例为 80/443；仅显式加入所需公开端口 | `CHORUS_TEST_DISABLE_WORKER=true` 仅供 `CHORUS_ENV=test` 的 Playwright fixture 使用。测试 helper 位于 `portal/web/e2e/fixture`，会按构造用户归属写入受控状态和测试图片；不得打包部署，也不得用于开发或生产数据。mock 上游的自动测试通过依赖注入连接本地 fixture，不允许把回环地址加入生产 SSRF 白名单。 diff --git a/docs/10-deployment-and-operations.md b/docs/10-deployment-and-operations.md index eb2f422..fb207d1 100644 --- a/docs/10-deployment-and-operations.md +++ b/docs/10-deployment-and-operations.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Deployment-and-Operations wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Deployment-and-Operations.- -wiki_revision: f75c6883edc8dc431fc04cac1dee22aa2515e0d5 -synchronized_at: 2026-08-25T07:01:43Z +wiki_revision: 0d4ce672c3b159fb67327314ab2073a7c5b39e03 +synchronized_at: 2026-08-25T07:10:02Z # 部署与运维 @@ -121,13 +121,13 @@ MVP-0 的终端用户会话保存在单个 portal 进程内存中，Cookie 只 portal 单二进制会同时启动 HTTP server 和内嵌 worker。启动必须显式传入 `--config `。下列 Provider/worker 参数以 YAML 为基础值，同名环境变量可逐项覆盖： -| 变量 | 约束 | -|---|---| -| `CHORUS_WORKER_LEASE_SECONDS` | 正整数；必须大于 `CHORUS_PROVIDER_HTTP_TIMEOUT_SECONDS + 5` | -| `CHORUS_WORKER_POLL_MILLISECONDS` | 正整数；控制空队列轮询间隔 | -| `CHORUS_PROVIDER_HTTP_TIMEOUT_SECONDS` | 正整数；安全 HTTP client 总超时和响应头超时 | -| `CHORUS_PROVIDER_MAX_RESPONSE_BYTES` | 正整数；Provider JSON/Base64/下载响应读取上限 | -| `CHORUS_PROVIDER_ALLOWED_PORTS` | 可选的逗号分隔端口白名单；默认 `80,443`，仅在受控变更后加入所需公开端口 | +| YAML 字段 | 环境覆盖变量 | 约束 | +|---|---|---| +| `worker.lease_seconds` | `CHORUS_WORKER_LEASE_SECONDS` | 正整数；必须大于 Provider HTTP timeout + 5 | +| `worker.poll_milliseconds` | `CHORUS_WORKER_POLL_MILLISECONDS` | 正整数；控制空队列轮询间隔 | +| `provider.http_timeout_seconds` | `CHORUS_PROVIDER_HTTP_TIMEOUT_SECONDS` | 正整数；安全 HTTP client 总超时和响应头超时 | +| `provider.max_response_bytes` | `CHORUS_PROVIDER_MAX_RESPONSE_BYTES` | 正整数；Provider JSON/Base64/下载响应读取上限 | +| `provider.allowed_ports` | `CHORUS_PROVIDER_ALLOWED_PORTS` | 非空端口列表；仅在受控变更后加入所需公开端口 | Provider API Key 由授权管理员通过管理端写入 `provider_credentials.api_key`。数据库、备份和管理员会话泄露会直接暴露完整 Key；必须限制数据库和管理端权限，列表/普通详情/日志/audit 禁止返回完整值，单条读取响应禁止缓存。部署环境不再需要 `CHORUS_MASTER_KEY`。