# 容量规划与调优

> 核验版本：1.1.0；通道：stable；文档 ID：operations.capacity

不存在跨硬件统一吞吐指标或笼统 HA 保证。容量取决于**你的脚本、依赖、负载、数据库、对象存储和部署限制**。主机/容器运维负责资源上限，开发者负责合理脚本预算和幂等；增加并行前双方需协调。

## 建预算，而非一个并发数字

| 组件 | 默认/约束 | 预算含义 |
| --- | --- | --- |
| 共享热池 | 16 槽、队列 32、等待 5 秒 | Python/TypeScript 短任务进程与导入；独占槽另外增加 |
| 长任务通道 | 8 并发、同步等待 5 秒 | 一次性进程可占内存数分钟；持久队列可等待而不拒绝 |
| 流式通道 | 8 并发、等待 30 秒 | 长期占连接/进程，慢消费者/代理缓冲会钉住资源 |
| 异步在途 | 每进程 128 | 独立准入限制，不是 128 份保证 CPU |
| 持久队列 | 每键等待 1000，纯延迟 100000 | 行保留请求/身份/目标；队列年龄与深度同样重要 |
| 平台 PostgreSQL | 每进程池 10，加其他连接 | 为通知/后台/管理/备份预留；没有受支持池大小环境变量 |
| 业务库缓存池 | PostgreSQL/MySQL 通常每资源/进程 8 | 乘活跃资源和实例数，同时考虑数据库自身额度 |
| WebSocket | 每进程 10000，队列 32，消息 64 KiB | 是协议上限不是实测支持量，内存/FD 可能更早到顶 |
| 响应缓存 | 默认每进程权重预算 64 MiB | 另有元数据/分配器开销；Redis 也须独立规划 |
| 上传/构建/日志 | spool、uv、Cargo target、产物和日志 | 分开预算磁盘、inode、IO；产物 LRU 不限制 Cargo target |

准确解析、覆盖和作用域见[运行时](../configuration/runtime.md)、[存储](../configuration/storage.md)、[网络](../configuration/network.md)。一次性/进程内 SQL/资源调用和工作流 fan-out 不都受共享池限制，共享池不是万能进程/查询总闸。

## 建立代表性基线

在隔离预生产项目用脱敏真实输入和相同解释器/镜像类别，分别测量：

1. 冷依赖/构建和热执行；只测热路径会隐藏发布/首调用故障。
2. 短同步、长异步、流式、嵌套/并行工作流及数据库密集目标。
3. 端到端 p50/p95/p99、队列等待/年龄、拒绝/超时率、CPU、RSS/峰值、PID/线程、FD、数据库连接/锁及磁盘/inode 增长。
4. 依赖/缓存/收集器失败及重启恢复。未经明确批准，不调用付费或真实 provider。

资源耗尽前停止，记录负载、版本、限制和实测。每次改一组控制，用同一负载复测，为重启、后台清理和突发保留余量。一次请求成功不等于可持续容量。

## 容器与编译约束

Compose/部署脚本示例 **512 PID、4g 内存** 只是起点，不适合所有负载。Docker PID 额度包含线程，Cargo/rustc 会产生远多于几个进程的线程数。编译节点通常需要单独实测的预算和受控 `CARGO_BUILD_JOBS`；把编译竞争移出低延迟执行节点可能有帮助，但不自动成为受保证 HA 拓扑。

失控分配或 fork 可杀死整个容器。保留内存/PID 限制及安全约束，不要通过永久无限资源或 `seccomp=unconfined` 修复。不同 worker UID 不是每脚本 cgroup 沙箱。FD 限制应在测量后由服务管理器/容器主机配置，不存在可随意发明的 Viat 环境变量。

实际 Docker 主机上的**未执行只读观察模板**：

```sh
docker stats --no-stream viat-server
docker inspect --format '{{.State.Status}} {{.RestartCount}}' viat-server
docker logs --since 15m viat-server
df -h
df -i
```

日志私下查看，容器名须匹配实际部署；这些命令不自动测定或修改生产容量。

## 多节点行为及限制

共享 PostgreSQL 节点协调已发布路由刷新、认领/租约和部分后台任务；热 worker、默认响应缓存、端点限流桶仍属本地。共享 Redis 缓存与限流分别启用，限流故障退回本地，缓存故障视为 miss。共享产物/依赖缓存要明确持久化，并协调工具链/架构。本地文件监听/存储不会自动复制。

节点间主密钥/JWT、公共 URL、后端和兼容产物应一致。合计整个集群数据库/资源连接及外部配额。按真实拓扑验证负载均衡、流式/WebSocket 与节点中断。就绪探针刻意**不因已有数据库池连接都忙就摘除节点**，`pool:saturated` 可以返回 200；因此不能用 readiness 代替负载监测。

锁/租约/心跳减少重复工作，不承诺 exactly-once 或零中断。数据库/网络分区和已提交外部动作仍需幂等。部署脚本强制替换单容器，不是 HA 滚动编排器。

## 对因调参

- READY 超时：先修包、缓存、工具/源并预热持久化，不是先调执行超时。
- 503 等待：查共享/长任务/流式通道、时长和下游限制，不要只扩所有队列。
- 数据库池/锁等待：降低 fan-out、修查询/事务、预留容量；增副本可能更糟。
- 大输出/上传占内存：使用支持的流式接口，保留 helper/entry 限制；缓冲增大会乘以并发。
- 队列增长：限制生产者、合理分工，优先幂等恢复，监测最老年龄。更多积压不是更高吞吐。

调参后若错误/延迟/资源恶化，恢复基线并留试验记录，在新限制下复核[备份](backup-restore.md)、[告警](alerts.md)和[升级](upgrades.md)。