# Nginx 本地激活组件

本组件负责受限的 Nginx 管理证书事务，不是完整的管理证书自动续期协调器。当前不能仅凭组件测试通过就解除应用内代理续期保护。

## 权限边界

- `scert-nginx` 独立命令只在 Linux 上运行，以 root 身份加载 root 所有且不可由其他用户写入的独立策略文件。
- 仅接受 systemd 提供的单个 Unix 流监听器，验证进程编号、描述符数量和固定 socket 路径；不自行监听 TCP、不删除 socket。
- 服务端通过 `SO_PEERCRED` 核对固定非 root UID；客户端同时验证 socket 路径及父目录和服务端内核 UID。
- 请求不能提供命令、配置路径、证书磁盘路径、上游地址或域名；这些值只能来自独立策略。策略引用的 Nginx 配置及其 include 依赖仍须由部署者维护为可信配置。
- `Directory` 及其版本目录为激活器所有的 0700 目录，私钥、证书、事务文件使用 0600。应用主进程不获得 Nginx 重载权限。

## 协议与事务

协议为四字节大端长度前缀和 JSON，版本为 1，帧上限为 2 MiB，拒绝未知字段和尾随内容。并发连接上限为四个；事务冲突直接返回失败，由协调者查询状态，不自动重放变更操作。

| 动作 | 行为 |
| --- | --- |
| `ready` | 检查不存在未决事务、双层 TLS 和专用证书材料一致、Nginx 配置合法 |
| `state` | 返回事务编号、状态和两张叶证书的 SHA-256，不返回私钥或磁盘路径 |
| `stage` | 验证候选，持久化事务并仅切换 Nginx，成功后返回随机事务编号 |
| `commit` | 确认双层已使用候选证书，再记录提交 |
| `reconcile` | 依据实际上游证书回退或提交；无关证书、上游不可用或外部变更时保留未决事务 |

`stage` 的应答丢失不等于没有执行。调用方必须用 `state` 查询，并结合持久化的候选摘要核对事务，不能直接重新申请证书或重试暂存。重复 `commit` 不返回幂等成功，调用方须确认查询到的是同一事务的提交终态。`reconcile` 对已完成的同一事务返回原终态，不代表重新验证了当下入口状态。

激活等待要求三次间隔 100 毫秒的新连接探测连续通过，每次严格核验证书链、域名、叶证书及 Scert 就绪响应。该检查降低平滑重载过程中偶然命中新工作进程导致的误判，不构成对未来所有连接的保证。

停止服务会取消活动请求并等待有界回退；监听器异常关闭报告错误。请求持有的私钥切片及帧缓冲在返回路径清理，但不声明能够擦除 Go 运行时或 JSON 解码器产生的所有内部副本。

## 接入前要求

1. 安装独立 socket/service，固定调用 UID，初始化专用版本目录并让目标站点引用 `active.conf`。
2. 应用须持久化旧状态、候选摘要、激活阶段和关联事务；完整生命周期必须串行化，不能在恢复检查上游之后并发切换上游。
3. 覆盖代理暂存、上游配置持久化与内存切换、代理提交之间的中断及应答丢失，并在启动时先恢复再允许申请下一张证书。
4. 不可将本组件的 `Recover` 视作双层恢复。它只回退代理；`Reconcile` 也必须由了解应用持久化状态的协调者调用。
5. 当前没有自动恢复循环、请求编号幂等机制或租约超时策略，不能宣称已具备无人值守续期闭环。

## 验证范围

Windows 测试只能覆盖通用协议和 TLS 探测。Linux 测试覆盖目录、文件、Unix 身份、策略、事务及继承监听器；真实 Nginx 用例需显式指定 `SCERT_TEST_NGINX_BINARY`。不同 UID 测试需在隔离 root 单元中设置 `SCERT_TEST_ROOT_IPC=1`，只在临时目录中复制测试程序并降权子进程，不修改真实用户或正式 socket。

实机执行命令、程序摘要和失败修复记录见仓库 `doc/Linux生产流程测试记录.md`。