首次 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。
正式应用构造函数拒绝未初始化配置。
前端初始化向导迁移至 Bootstrap API，加入令牌兑换、三数据库选择及验证、通知对象和完成跳转。
新启动和前端链路验证通过后，停止注册旧初始化路由，保留旧源文件。
新版 Linux 发布包、桌面浏览器和真实数据库整链路验收。
在明确授权范围内进行真实 DNS、ACME、HTTPS 和远程部署验收。

本轮验证

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

go test ./...
go vet ./...
go test -race ./internal/bootstrap ./internal/config ./internal/setup
go test -race ./...
git diff --check

另外，设置 GOOS=linux、GOARCH=amd64、CGO_ENABLED=0 后执行 go build ./... 通过，仅验证 Linux 目标源码可构建，没有生成或部署本轮 Linux 发布包。

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

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

关键设计与续接注意事项

配置提交边界

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

验证凭据的事务所有权

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

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

通知兼容

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

前端迁移时应将现有通知表单映射到该对象，而不是移除通知步骤。不要把客户端输入或底层错误写入公开响应。

验收与操作边界

当前新路由尚未接入 scert serve，现有启动行为和旧前端没有因为上述模块测试通过而自动完成迁移。
IP 管理入口目前使用自签名证书，不能表述为已获公共 CA 信任。
本轮未连接远程主机，未操作真实 DNS，未清空既有数据库，未修改 pcux.cn 及其证书。
47.108.78.12 用于项目部署；8.137.23.95 用于推送测试，两者不可混用。
历史未跟踪补丁、测试脚本、二进制和 dist/ 产物保持不动，不纳入提交。

下一步

先实现可注入依赖的启动状态机及隔离 HTTPS 服务，并补充启动、关闭、配置损坏和完成切换测试。之后迁移前端，再做真实浏览器与 Linux 发布验收；不要提前停用旧路由导致现有向导不可访问。

6.0 KiB Raw Blame History Unescape Escape