> 2026-09-23 更新：以[统一登记与逐次发布规则](registration-gated-release.md)为后续实施目标。所有已登记项目的代码和部署配置统一纳入，账号、密钥、权限由管理员维护。下文的逐账号配置属于现有入口/首次开通说明，不应当作为每次发布都要手工改权限的要求。统一发布闸门尚未全部接通。

# 维护者接入与代码发布工作流

版本 1.0 · 核对日期 2026-09-21 · 面向管理员、项目负责人、维护者及其 Agent。

本指南定义可复用的工作流和交接材料；不是已完成多租户适配的一键安装器。现有大陆工具限制为试点账号 gpt@zfold8，电芯发布器限制为固定项目和部署方式。新账号、新项目必须先适配工具并通过验收，不能只改 sudoers，也不能复用别人的私钥。

## 先选择你的情况

- 已获授权的试点维护者修改电芯：按“日常提交”操作，登记发生在实际发布的服务器。
- 同一项目新增维护者：管理员核验身份、建立独立账号和密钥映射，再配置工具内部授权；通过拒绝测试后交接。
- 新服务器或新项目：先完成“项目接入”，确定源码、服务、健康检查、回滚和审计出口，再授权维护者。
- 仅查看审计：走管理台账号授权，无须提供 SSH 写权限。

## 当前真实状态

- 香港：电芯 src/public 已允许登记；香港登记工具记录源码前后差异，本身不发布代码。当前维护账号仍有完整 sudo，其他直写路径未被全局封锁。
- 大陆：电芯登记、受控提交和发布工具已安装，sudo 命令权限及审计导出已核对。已读取两条电芯生产发布成功回执（20260921T032549Z-41061733、20260921T033436Z-e8471915）。业务验收与多账号接入仍需分别核对；先前12项隔离测试中的部署命令是模拟测试。
- 两地审计：可通过本机同步工具导出并导入香港管理台。是显式同步，不是常驻实时同步；同步成功必须单独确认。
- 其他人员：尚未提供可直接安装的通用多账号工具包。现有脚本中的 ACTOR、SUDO_USER 检查、项目路径、导出来源与本机 SSH 配置都需适配；本页模板不会自动授予权限。

## 角色与责任

| 角色 | 负责什么 | 交付给下一步 |
| --- | --- | --- |
| 项目负责人 | 确认应用、代码范围、自动发布条件、业务验收人 | 填好的项目策略 |
| 服务器管理员 | 核验公钥、开账号、安装受控工具、配置精确 sudo 权限、测试撤销 | 授权回执、主机指纹、工具版本 |
| 维护者 / Agent | 修改前登记、提交确切版本、运行业务检查、核对发布与同步结果 | 登记号、候选摘要、检查证据 |
| 发布工具 | 验证身份、范围、基线、候选版本；执行固定发布步骤 | 系统生成的发布或失败回执 |
| 审计管理员 | 控制谁可查看差异，检查同步及异常 | 归档与问题处理记录 |

## 完整流程

项目接入 → 身份核验 → 管理员一次授权 → 验收交接 → 修改前登记 → 提交候选 → 校验 → 受控发布 → 业务验收 → 审计同步 → 归档。

登记失败不能进入提交；校验失败不能进入发布；发布成功但同步失败，保留“已发布 / 同步失败”两个独立状态，不能重新发布来解决同步问题。

## 项目接入：管理员先收齐这些资料

下载 project-policy.json，填写项目 ID、目标服务器、精确源码根目录、允许目录和后缀、排除目录、固定服务及发布命令、健康检查、备份与回滚方式、审计导出入口、责任人。模板中的 null 和 REPLACE_REQUIRED 必须填完。

接入检查：确认该目录确实是运行服务的构建来源；确定静态文件、容器镜像或系统服务的实际部署方式；记录服务身份和数据挂载。不得从目录同名、存在 Dockerfile 或另一台服务器的登记号推断发布目标。

现有电芯适配器只支持既有 Docker Compose 电芯服务，src/public 内的 JS/MJS/HTML/CSS/JSON/MD；最多20个文件、单文件2MiB、请求8MiB；已有父目录；不接受删除。数据库迁移、依赖更新、Dockerfile、Compose、系统配置、密钥、图片等不在此通道内，须另做适配和授权。

新项目的工具版本必须先在隔离环境验证；没有对应发布适配器时，只能标记“可登记 / 可提交 / 不可发布”，不能发放全量 sudo 作为临时替代。

## 身份与管理员授权

详细步骤见 admin-authorization.md。维护者提交 maintainer-request.json 和 SSH 公钥，通过独立渠道核对指纹。私钥留在维护者设备。

一名维护者的一台设备使用独立密钥；Agent 名称和设备标签是声明，实际系统身份来自 SSH 账号、公钥认证证据及 sudo 用户。多个 Agent 共用同一账号或密钥时，不能声称已区分各自身份。

管理员建立“维护者 → 账号/密钥 → 项目 → register/submit/publish/export 能力”的授权映射，记录授权人、理由、日期、撤销方法。模板中的到期时间只是管理记录，当前试点工具不会自动到期撤权。

账号能登录、项目能登记、工具内部允许该身份、sudo 允许固定入口，是四个分别要验收的条件。任何一个缺失都不能靠修改登记说明绕过。

## 日常提交：大陆电芯现有入口

先阅读项目 AGENTS.md 和本指南。命令在目标大陆服务器上以已获授权的 gpt@zfold8 执行；其他账号不得照抄账号名。把文件放在自己的工作目录，登记前不要直接修改生产文件。

登记 JSON 示例（将文件路径替换为本次真实范围）：

```json
{"task":"CELL-任务编号","summary":"修改内容","reason":"修改原因","paths":["/home/ubuntu/apps/cell-qr-app/public/index.html"]}
```

```sh
sudo /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/register.py begin < spec.json
```

保存返回的 registration_id；将下面命令中的 REGISTRATION_ID 替换为该编号。香港审计号、网页 CHG 编号及已完成记录不能代用。

先在本地或隔离工作目录改代码并执行业务测试，再生成 files.json；content 必须为完整修改后文件内容，不是 diff。提交路径必须与登记集合相同。

```json
{"files":[{"path":"/home/ubuntu/apps/cell-qr-app/public/index.html","content":"完整修改后源码"}]}
```

```sh
sudo /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py submit REGISTRATION_ID < files.json
sudo /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py publish REGISTRATION_ID
sudo /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py status REGISTRATION_ID
```

submit 校验身份、范围和基线，检查 JS/JSON 语法，保存不可变候选，不修改生产文件。publish 再次校验版本，备份源码与原镜像，只部署预先配置的服务；失败尝试回滚并保存结果。普通范围内的发布不需要管理员逐次批准，但首次授权与部署适配必须完成。

自动检查不代替项目测试。业务验收人还需确认登录、核心页面和相关 API；工具不会把人工自报的测试结果当作系统验证。代码/镜像回滚不会回滚数据库。

## 香港源码留痕的区别

香港使用 /usr/local/lib/njwl-agent-changes/agent-submit.py register spec.json，spec 需要 agent、environment、task、summary、reason、paths。修改后执行同工具 submit 登记号 --checks checks.json。

这个 submit 只记录实际修改，返回“已完成未发布”，不接收大陆候选包也不执行部署。大陆受控发布必须取得大陆登记号。跨站任务在 task 中记录相同业务任务号便于查找，但这不是跨站授权凭证。

## 跨服务器审计

现有试点：在维护者本机运行以下脚本，使用本机现有 SSH 身份从大陆导出脱敏记录、校验摘要后导入香港。

```sh
python3 /home/desktop/Desktop/gpt/njwl-workspace-android/maintenance/sync-mainland-records.py
```

该本机绝对路径仅适用于试点设备，其他部署不能照抄。新部署须由管理员配置导出端、接收端、独立采集身份、允许命令和受控导入位置，并测试失败重试与去重；不要复制试点私钥。没有常驻采集服务时，明确由谁在何时执行同步。

查看 https://njwl.ai/sso/#agent-changes：确认来源服务器、原始登记号、发布状态、时间、差异和同步时间。原始快照留在源服务器受限目录；页面只展示经过筛选的差异。SHA256 用于一致性检查，不代表数字签名或对 root 不可篡改。当前固定导出最近500条；新部署需另行制定归档与保留周期，避免把列表上限当作备份策略。

## 异常与恢复

| 情况 | 应该怎么做 |
| --- | --- |
| No such user | 先由管理员确认系统账号存在；设备标签不一定是登录用户名 |
| 登记路径不允许 | 核对实际目标服务器与源码路径，管理员审查项目范围后配置，不事后补登记 |
| sudo 要求密码 / 拒绝 | 核对精确命令、解释器 -I 参数、脚本路径及工具内身份授权；不要放开通用 shell |
| 线上基线已变化 | 读取新版本、合并变化、重新登记与提交；不得强制覆盖 |
| 候选已存在 / 登记已结束 | 保留旧记录，新版本使用新登记号 |
| 发布失败且已回滚 | 核对回执与业务状态，修复后建立新任务 |
| 发布中断或只有开始回执 | 停止重复发布，管理员核对运行镜像、源码摘要和原始回执 |
| 发布成功但同步失败 | 只重试同步；原发布状态不变 |
| 主机密钥改变 | 管理员通过独立渠道确认原因与指纹，不能关闭 StrictHostKeyChecking |

## 验收与交接

下载 acceptance.md，逐项填写实际结果和证据，未执行标“未验证”。首次项目接入需做一次低风险的真实变更、业务验收和审计同步，随后才能称为完整工作流跑通。

给下一位维护者交付 handoff.md：目标主机和指纹、项目路径、工具版本、可用能力、登记/提交/状态命令、检查及回滚方式、审计入口、管理员联系方式。不得交付私钥、令牌、完整环境文件或生产数据。

人员退出时撤销该公钥及对应 sudo 和工具内部授权，检查已有会话、在途发布及未结束登记。仅删除公钥不终止已经建立的 SSH 会话；停用前先由管理员确认是否存在正在写入的发布任务。保留历史审计和撤销记录。