zhuangxiu/docs/settings.md

可视化系统设置

为什么不再把所有内容放进 .env

.env 只负责应用启动前必须存在的 PostgreSQL、Redis、监听地址和运行期设置目录。数据库和 Redis 必须先启动，网页设置才有机会打开，因此它们不能完全由已运行后的网页管理。

scripts/bootstrap.ps1 使用操作系统的加密随机数一次性生成数据库和 Redis 密码，不依赖 OpenSSL，也不会在终端打印密码。普通用户不需要打开 .env。

以下内容改为网页配置并加密保存：

• NAS MinIO 与三个 bucket。
• 百度 OCR。
• 总调度、空间理解和生图模型。
• 本地或局域网 GPU Worker。
• Langfuse 与 Sentry。

分类与门禁

工作流必备分类为：

1. 基础运行：PostgreSQL、Redis、配置加密。
2. 文件存储：MinIO 地址、服务账号和三个 bucket。
3. AI 模型：统一 API、总调度模型、空间理解模型和生图模型。

必备分类既要填写完整，也要通过对应连接测试。未完成时，上传和工作流命令接口返回 SETTINGS_INCOMPLETE，前端“开始设计”按钮保持锁定。

百度 OCR、GPU、Langfuse 和 Sentry 是条件必填：关闭时不影响工作流；开启后应填写完整并测试。

聚合引擎 AIGC

聚合引擎按 OpenAI 兼容网关接入，设置项包括：

• API Base URL。
• API Key。
• 总调度模型 ID。
• 空间理解模型 ID。
• 默认生图模型 ID，预设为 gpt-image-2。
• 高级路径：/models、/chat/completions、/images/generations、/images/edits。

平台的公开文档入口在未登录状态下会跳转首页，因此 Base URL 不在代码中猜测或写死。用户从登录后的开发者文档复制一次即可，随后“验证 API 与模型”会调用模型列表接口，检查 Key 和三个模型名。

为什么本地 GPU 仍然需要 Worker

网页和 Docker 容器不能安全、稳定地直接执行宿主机 CUDA。把 GPU 推理拆成 Worker 可以隔离模型依赖、显存崩溃和长任务，并允许未来迁移到独立 GPU 服务器。

设置页提供三种自然语意选项：

• 暂不使用：全部调用云 API。
• 本机 GPU Worker：无需输入地址。原生运行 API 时自动访问 127.0.0.1:8100；Docker 中自动访问 host.docker.internal:8100。
• 局域网 GPU 服务器：仅此模式需要填写内网地址。

GPU 主要用于户型分割、深度估计、几何校验和可选本地视觉模型。云端生图 API 本身不需要本地 GPU。

密钥安全

• 运行期配置加密写入 .runtime/settings.enc。
• 主密钥保存在 .runtime/.master-key 或 Docker 的 settings-data 私有卷。
• 密钥接口只返回是否已配置；保存成功后浏览器会清空输入值。
• 测试请求由后端发出，密钥不会直接交给第三方网页脚本。
• 当前版本应部署在可信内网；正式开放公网前还需给设置接口增加所有者登录和权限控制。