rust-deployable-service

Rust 可部署服务

当 Rust 服务需要从本地开发转向可重复的容器或云端部署时，使用此技能。保持运行时配置明确、构建可复现，并让健康检查简单可靠。

核心工作流

1. 检查 Cargo.toml、工作区布局、Dockerfile、.dockerignore、 配置文件、迁移文件、.sqlx/、CI 和部署文档。
2. 确定二进制入口点和运行时依赖：数据库、Redis、 外部 API、TLS 根证书、静态文件、模板、迁移文件和配置。
3. 分离构建时配置和运行时配置。切勿将生产密钥烘焙进镜像。
4. 使用分层配置，并通过环境变量覆盖部署专用的值。
5. 使用多阶段 Docker 构建，并仅将运行时二进制文件和所需资源复制到最终镜像中。
6. 考虑 SQLx 查询检查。使用 SQLX_OFFLINE=true 和已检入的 .sqlx/ 元数据，或有意提供构建时数据库。
7. 添加符合实际依赖情况的健康检查和就绪检查。
8. 运行随附的 Docker 预检脚本，或仓库中对应的 CI 命令。

配置规则

添加配置文件、环境变量或处理密钥时，请阅读 references/configuration.md。

• 保持本地默认值易于使用，并让生产默认值更保守。
• 尽可能在绑定服务器之前，于启动时验证配置。
• 将密钥存储在环境变量或部署平台的密钥管理器中。
• 避免在处理程序或存储库深处读取环境变量。

Docker 规则

修改 Docker 构建前，请阅读 references/docker-rust.md。

• 有策略地使用依赖缓存；在可行时，避免每次修改源代码都使整个构建缓存失效。
• 如果仓库提交了 Cargo.lock，发布构建时使用 --locked。
• 需要出站 HTTPS 时，包含 CA 证书。
• 只有在运行时需要时，才复制迁移文件、模板和静态资源。
• 如果部署平台支持，以非 root 用户身份运行。

验证

如果交付流程包含 Docker，请在 Rust 项目根目录运行：

path/to/rust-deployable-service/scripts/docker-preflight.sh

该脚本会构建镜像。只有设置了 RUST_DEPLOY_SMOKE_COMMAND 时才会运行冒烟命令，因为服务通常需要环境配置和基础设施才能成功启动。

参考文件

• references/configuration.md：类型化配置加载、覆盖、验证和密钥管理。
• references/docker-rust.md：多阶段构建、SQLx 离线构建、运行时资源和镜像检查。