首次 IP 初始化开发记录

已确认需求

无 GUI 的 Linux 首次启动允许通过服务器 IP 打开初始化页面。
完成配置后使用选定的域名或 IP 访问正式管理服务。
初始化支持 SQLite、MySQL、PostgreSQL 三种存储方式。
DNS 面向阿里云，保留多用户、通知及其他原有功能。
数据库和 DNS 验证通过后，由服务端保存验证状态；客户端不能通过传入凭据引用绕过验证。
初始化入口与正式管理服务分离，初始化未完成时不得启动正式业务和后台续期任务。

任务状态（2026-09-16）

这里的“复审通过”仅指对应代码和本地自动化测试，不代表浏览器、Linux 实机或生产验收通过。

[✓] 配置保存改用同目录随机临时文件；写入、权限、归属、同步和关闭全部在替换正式文件之前完成。
[✓] 配置保存覆盖首次保存、覆盖保存及各准备步骤失败的回归测试；失败不能改变原正式配置。
[✓] 新增 POST /api/v1/bootstrap/complete，强制初始化会话认证、正文限额、对象类型、未知字段和单段 JSON 校验。
[✓] 初始化完成接口按错误类别映射状态码，不向浏览器返回底层错误、密码或凭据引用；成功撤销会话并清除 Cookie。
[✓] 数据库和 DNS 验证结果支持原子领取；领取后令牌不能重复使用，凭据回收责任交给初始化事务。
[✓] 过期清理、其他验证操作和批量清理不能删除事务持有的凭据；保存失败时精确回收本次领取的凭据。
[✓] 补齐 32 个并发请求的唯一领取及一次性回收测试，并通过竞态检测。
[✓] 初始化支持 HTTP、SMTP 通知配置；省略通知对象保留已有设置，新密码只交给敏感信息存储。
[✓] 通知凭据部分写入失败、配置保存失败时回收本次新凭据，保留原有凭据。
[✓] 显式关闭通知重试不再在配置重新加载时变回三次重试。
[✓] 正式管理地址支持 IPv4、IPv6、默认及非默认 HTTPS 端口；代理模式不输出内部监听端口。
[✓] 初始化提交测试夹具显式隔离所有可写目录，避免 Linux 默认路径指向 /scert 或 /ssl。
[✓] CLI 启动状态机：未初始化进入独立 Bootstrap HTTPS，已初始化进入正式应用，损坏配置失败关闭。
[✓] 接入 --bootstrap-public-ip、SCERT_BOOTSTRAP_PUBLIC_IP 和 /run/scert/bootstrap-url；systemd 为临时地址提供受保护运行目录。
[✓] 正式应用构造函数拒绝未初始化配置，正式监听器不再提供未初始化明文 HTTP。
[✓] 前端初始化向导迁移至 Bootstrap API，加入令牌兑换、三数据库选择及验证、通知对象和完成跳转。
[✓] 正式服务不再注册旧初始化写接口，仅保留状态查询；未初始化桌面端保留本机向导和旧源文件。
[✓] 桌面端已取得的处理器在配置保存后自动激活正式服务，无需重启窗口即可登录；并发切换、幂等关闭、取消在途初始化和损坏配置均有回归测试。
[✓] 初始化写请求拒绝跨源访问；前端最终提交重新校验所有步骤和令牌有效期，避免响应乱序、计时缓存及重复提交绕过。
[✓] 临时 HTTPS、SQLite 初始化、正式 HTTPS 同端口切换、管理员登录和会话可用性通过隔离集成测试。
[✓] 复审三库接入后的备份恢复兼容性：MySQL 接入加密凭据，PostgreSQL 未实现完整备份时明确拒绝，禁止漏备份却报告成功；内存凭据与拒绝操作的回归测试通过，不代表真实数据库备份恢复已验收。
[!] PostgreSQL 完整备份恢复尚未实现，不能宣称三种数据库的全部运维能力均已完成。
[!] 新版 Linux 发布包和桌面浏览器验收：本地独立服务启动及发布脚本执行此前被策略拒绝，未绕过限制。
真实 MySQL/PostgreSQL 的连接、迁移、权限及完整业务链路验收。
Linux 最小权限 systemd 下的初始化、防火墙及管理入口切换验收。
在明确授权范围内进行真实 DNS、ACME、HTTPS 和远程部署验收。

本轮验证

在 Windows 开发工作区执行并通过：

go test -p 1 -count=1 -timeout=4m ./...
go test -race -p 1 -count=1 -timeout=5m ./...
go vet -p=1 ./...
go mod verify
git diff --check

桌面模块的 Go 测试、竞态检测、go vet、依赖校验及 go mod tidy -diff 通过；桌面端依赖已同步后端的 PostgreSQL 驱动等间接依赖。

前端 npm.cmd test 共 38 项通过，覆盖初始化令牌兑换、三数据库表单、完整向导提交、通知映射、过期令牌、错误响应及 DNS 等待状态。前端生产构建通过，产物写入新的 .runtime/frontend-bootstrap-20260916-2030，未清理旧产物；生产依赖审计未报告漏洞。

另外，设置 GOOS=linux、GOARCH=amd64、CGO_ENABLED=0 后执行 go build -p 1 ./... 通过，仅验证 Linux 目标源码可构建，没有生成或部署本轮 Linux 发布包。2026-09-16 20:35 已收齐新增维护检查后的全量测试、竞态检测、静态检查和 Linux 交叉构建结果，均通过。

测试使用独立临时目录和隔离 SQLite 数据库；阿里云验证、证书签发和防火墙由测试替身模拟，没有修改真实 DNS 或主机防火墙。

MySQL/PostgreSQL 参数、验证状态和凭据处理有自动化覆盖，但这不等于本轮完成两个真实数据库服务的连接、迁移和权限验收。HTTP 接口测试不等于浏览器验收。通知配置测试不等于实际邮件投递。

HTTPS 集成测试只连接本机回环地址，严格校验证书及名称，不使用跳过 TLS 校验。临时初始化结束后，在同一端口启动正式服务并验证登录、会话、管理员接口和 /readyz。这里的就绪结果仅证明隔离夹具中的配置、SQLite 和加密凭据可用，不代表真实 RAM 权限、证书信任或远程生产就绪。

关键设计与续接注意事项

配置提交边界

Config.Save 只有正式文件替换成功才返回成功，替换之后不再执行可能返回错误的权限操作，避免调用方错误回滚已提交的证书和凭据。代码不保证断电后的目录项持久性；Linux 目录归属及权限准备仍可能产生元数据副作用。

验证凭据的事务所有权

Claim 在验证管理器的互斥锁下读取并移除有效令牌，返回验证结果和仅能执行一次的失败回收函数。Completer 成功保存配置后不调用回收函数；任何提交前失败都尝试回收。旧 Resolve、Check、Consume 保留给原有调用方，但新 Bootstrap 提交不再采用“先读取、最后消费”的模式。

此机制覆盖当前进程内的受控失败，不承诺进程强制终止后的孤立临时凭据自动恢复；后续启动清理机制应单独复审。数据库迁移和管理员写入可能已发生，不能宣称所有数据库副作用可回滚。

通知兼容

完成请求通过可选 notification 对象传递通知配置。省略对象保留原有配置，提供对象按完整表单应用；客户端不能指定 http_credential_ref 或 smtp_credential_ref。HTTP 支持 Bearer、HMAC-SHA256 和账号会话认证；SMTP 密码单独存储。

前端现已将原通知表单映射到该对象，通知步骤保留。不要把客户端输入或底层错误写入公开响应。

三库运维边界

新增数据库加密引用后，MySQL 维护操作必须在内存中解密账号再建立连接，不能直接使用无账号的持久化 DSN。恢复前应固定可用连接，避免配置和主密钥替换过程中失去快照或回滚连接。备份校验必须包括数据库凭据引用。

PostgreSQL 当前可选择初始化，但原完整备份实现只有 SQLite/MySQL。本轮先让 PostgreSQL 的 backup、restore 明确失败，在创建输出或替换目标前阻止不完整备份被当作成功。完整实现及真实恢复演练仍是生产准入阻塞，不能把这一防护当作备份功能开发完成。

验收与操作边界

新启动链路已接入 scert serve，但独立服务的实际页面渲染和新版本 Linux 部署仍未验收。
IP 管理入口目前使用自签名证书，不能表述为已获公共 CA 信任。
Bootstrap 临时证书仅保存在进程内；现有日志尚未提供可从可信运维通道对照的证书指纹，正式发布前应补齐首次证书身份核对流程。
当前初始化仍调用防火墙管理器。systemd 使用非特权 Scert 用户且不授予网络管理能力；存在 UFW/firewalld 时必须验证只读检查和权限失败处理，不能要求把整个服务改成 root 来通过初始化。
本轮未连接远程主机，未操作真实 DNS，未清空既有数据库，未修改 pcux.cn 及其证书。
47.108.78.12 用于项目部署；8.137.23.95 用于推送测试，两者不可混用。
历史未跟踪补丁、测试脚本、二进制和 dist/ 产物保持不动，不纳入提交。

下一步

优先补齐 PostgreSQL 完整备份恢复、初始化证书身份核对及非特权防火墙处理；在允许启动服务和执行发布脚本的环境中完成浏览器与 Linux 发布验收。真实数据库和 DNS/ACME 测试必须使用专属测试数据与已授权域名，并明确测试范围，不能清空生产数据库或触碰禁止修改的域名。

9.4 KiB Raw Blame History Unescape Escape