配置模型与完整索引

配置模型与完整索引

本手册描述稳定版 1.1.0，不代表未来版本。首次部署请先阅读 Docker Compose 安装 或 二进制与源码安装。配置与运维章节中的所有命令都是待运维人员审阅的模板，编写文档时未执行。替换示例名称和凭据，确认副作用，并先在隔离环境验证，再用于生产。

配置入口

入口	操作者	持久性与优先级
进程环境变量	主机或容器运维人员	服务端没有通用 YAML 配置文件，也没有统一的配置重载 API。显式进程/容器环境覆盖镜像 ENV；未设置时使用下表中的实际运行时默认值。修改后重启或重建容器。
镜像与容器	Docker 管理员	镜像提供解释器、静态文件及部分默认值。Compose .env 只用于变量替换，不会自动注入进程；服务的 environment 等入口必须显式传入应用变量。
部署包装脚本	主机运维人员	deploy-server.sh 会把 .env 当作 shell 脚本加载，而非被动 dotenv 数据。只能使用可信文件。脚本变量不等于应用配置，参见网络配置。
实例设置	具有相应权限的平台 Owner/Admin	保存在 PostgreSQL，不能代替数据库连接、主密钥、监听或工作进程配置。
项目、端点、资源	具备相应编辑/发布权限的项目成员	草稿与已发布快照不同。端点认证、绑定和覆盖通常要发布才生效；草稿测试成功不代表已发布路由发生变化。
CLI/MCP 会话	本地客户端用户	.viat/config.yaml 与客户端环境，不是服务端参数，参见集成配置。

布尔值没有统一解析规则。有些开关只认小写 false/0，有些接受大小写不敏感的 no，有些启用开关必须严格写 1。安全开关拼错后，功能可能仍然开启。

变量表的统一约定

每项均说明类型、二进制实际默认值、单位/范围、校验与回退、作用域和覆盖关系。除标记为必填的项外，其余均可选。没有特别说明时，合法显式值替换运行时默认值；数字解析失败则使用列出的默认值。“未设置”不等于空字符串。u64、u32、u16、usize、i64 使用相应 Rust 整数范围；表中列出额外产品约束。usize 随平台位数变化。不要把理论最大值当作可运维值。

作用域与重载代码：

• S：启动或构建路由时读取，须重启。
• F：首次使用后进程内缓存，须重启。
• D：执行相关操作时读取；不提供从外部修改运行进程环境的通用机制。修改部署配置后仍需重启，不表示编辑 .env 会热加载。
• W：创建工作进程或编译进程时读取；现存工作进程不变。修改后重启并重建相关环境。
• C：CLI/MCP 本次调用，不作用于服务端；重新运行客户端。
• I：安装脚本、Compose 或镜像构建输入，不是服务端参数；确认副作用后重新部署/构建。

只有明确注明时，项目或脚本才可覆盖。端点作者不能突破部署上限。执行超时按目标声明 → 项目默认 → 部署默认选择，再受同步/异步上限约束。构建预算和代理超时是另一套参数。

按职责查找

• 数据库：平台 PostgreSQL、资源连接限制、迁移超时及真实 TLS 限制。
• 安全：密钥、令牌、初始账号、注册、MFA、工作进程身份、秘密后端和 SSRF 开关。
• 运行时：池、执行通道、运行/构建/队列预算、调度及 Rust 产物。
• 网络与部署：监听、公共 URL 与前缀、TLS、控制台/内置文档、WebSocket、Compose 及部署脚本。
• 存储：目录白名单、上传暂存、S3 缓冲/分段上传及产物持久化。
• 可观测性：日志、指标、追踪、行日志后端、历史及保留参数。
• 集成与客户端：SMTP、聊天/社交网关、包管理器、代理/CA 透传、CLI/MCP 和开发专用输入。

修改、验证与恢复

1. 记录当前版本、镜像摘要、部署文件、挂载和变更原因。不要把密钥值写入工单或进程命令行。
2. 核对该项的 Docker/二进制差异，以及单节点或共享作用域。多节点的密钥、公共 URL 和后端选择应一致。
3. 迁移、换密钥/后端或缩短保留期限之前，按备份恢复完成备份。直接替换主密钥不是轮换流程。
4. 修改服务实际环境。Compose .env 新增一行而不传入服务，不会生效。系统服务要使用服务管理器的环境配置；二进制自身不加载 .env。
5. 优雅重启并检查启动日志。启动会创建上限 10 条连接的平台数据库池、执行内置迁移、按需创建初始 Owner、初始化后端，并启动后台循环后开始服务。
6. 检查 /healthz、/readyz、需认证的 /version、登录和隔离项目请求。探针正常不代表激活、依赖、外部凭据或通知投递正常。
7. 配置问题可恢复上一组非破坏性配置再重启。数据库迁移回滚与被删除的数据必须按恢复流程处理，不能只换旧镜像。

运行时默认值不等于 Docker 默认值

二进制未配置时允许注册；官方镜像设为 VIAT_ALLOW_REGISTRATION=false。镜像还设置 VIAT_WEB_DIR=/app/web、VIAT_DOCS_DIR=/app/docs、VIAT_BIND=0.0.0.0:8080、VIAT_SHELL_BIN=/bin/bash、SCHEDULER_ENABLED=true、RUST_LOG=info 和 HOME=/home/viat。-build 镜像额外设置 Rust SDK、产物、目标目录及 Cargo/rustup 路径。普通镜像不含 Rust 编译器，即便二进制构建开关默认打开。部署示例中的 4g 内存和 512 PID 限制是容器示例，不是应用默认容量，也不是性能实测。

维护依据

本章核对了固定版本实现中的 crates/viat-api/src/config.rs（包括 AppConfig::from_env）、启动过程、运行时池/通道/Rust/账号配置、后端构造、Dockerfile、Compose 和部署脚本。集成配置另行分类测试专用、工作进程注入和构建工具变量；它们不是服务端开关。不以归档计划作为当前行为依据。