# 配置模型与完整索引

> 核验版本：1.1.0；通道：stable；文档 ID：configuration.overview

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

## 配置入口

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

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

## 变量表的统一约定

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

作用域与重载代码：

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

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

## 按职责查找

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

## 修改、验证与恢复

1. 记录当前版本、镜像摘要、部署文件、挂载和变更原因。不要把密钥值写入工单或进程命令行。
2. 核对该项的 Docker/二进制差异，以及单节点或共享作用域。多节点的密钥、公共 URL 和后端选择应一致。
3. 迁移、换密钥/后端或缩短保留期限之前，按[备份恢复](../operations/backup-restore.md)完成备份。直接替换主密钥不是轮换流程。
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 和部署脚本。[集成配置](integrations.md)另行分类测试专用、工作进程注入和构建工具变量；它们不是服务端开关。不以归档计划作为当前行为依据。