feat: 增加安全管理员 bootstrap 命令 (#19) #28

New Issue

2026-08-21T16:53:43+08:00

ila commented

2026-08-21 16:53:43 +08:00

基本信息

类型：安全配置
所属 Epic：#3
所属 MVP / 版本：#19 / MVP-1
阶段：已完成

原始需求

来源：用户对话。
提出时间：2026-08-21。
脱敏摘要：管理员账号使用 admin，凭据不得写入仓库；用户确认采用仓库外环境变量和一次性 bootstrap 命令的安全方案。

目标与范围

新增受显式调用控制的管理员 bootstrap 命令。在已完成 #20 迁移的数据库中，使用仓库外环境变量创建或维护 sys_user 的 admin 账号，并赋予 chorus_operator 角色。

账号名从 CHORUS_ADMIN_USERNAME 读取；部署配置把它设为 admin。
密码只从 CHORUS_ADMIN_PASSWORD 读取；不接受命令行密码参数，不写入代码、日志、响应、工单、Wiki、原型或测试 fixture。
命令默认只创建不存在账号；只有 CHORUS_ADMIN_RESET_PASSWORD=1 时才会重置既有账号密码。
使用固定 go-admin 兼容的 bcrypt 密码格式，账号状态为可登录状态；角色必须引用 chorus_operator，缺失时失败关闭。

不新增公开注册、找回密码、管理员网页登录流程、默认密码、AutoMigrate 或生产 dev-tools。

已确认方案

实现独立 cmd/chorus-admin-bootstrap（名称可随现有命令组织微调），只通过 CHORUS_DSN 连接已迁移数据库。命令先验证环境、确认 chorus_operator 角色和目标账号的状态，再在事务中创建账号或按显式 reset 标志更新 bcrypt hash。所有输出只描述结果，不回显用户名以外的敏感配置，更不回显密码或 hash。

现有管理员行被保留；不删除角色、菜单或 API 种子。#20 的迁移和用户验收是硬前置，未满足时不得开始实现。

依赖与并行

前置工单：#20（2026-08-21 已验收通过）。
关联工单：#24 后续 go-admin 运营界面可复用 bootstrap 后的管理员账号。
是否允许并行：否；必须先确认 #20 的可逆 sys_* 基线。

设计证据

类型：后端安全配置，无需 UI 原型。
替代设计：本工单的已确认文字方案；确认人：用户；确认时间：2026-08-21。
覆盖范围：外部凭据注入、显式重置、bcrypt 兼容、角色绑定、日志脱敏与失败关闭。

验收标准

缺少任一必要环境变量、DSN 不可连通、角色不存在或账号状态异常时失败关闭，且不写入账号数据。
首次执行在已迁移的隔离 MySQL 8 中创建指定管理员账号、bcrypt hash 和 chorus_operator 角色绑定。
不带 reset 开关的重复执行不修改既有 password hash；带 CHORUS_ADMIN_RESET_PASSWORD=1 的显式执行才更新 hash。
命令输出、错误、测试和文档不包含密码、hash、DSN 或其他敏感值。
受影响 Go 单元/集成测试、go build ./...、go vet ./...、go test ./... 通过；生产不调用 AutoMigrate。

验证与回退

在本机隔离 MySQL 8 使用临时环境变量执行创建、重复执行、显式重置和失败路径测试；测试结束清理构造账号。
回退是停用或删除本次构造的管理员账号，不改变终端用户 users、角色种子或迁移版本；不得以回退名义删除实际管理员数据。

实施记录（2026-08-21）

实现：新增 cmd/chorus-admin-bootstrap 与 internal/adminbootstrap。命令不接受参数，只读取 CHORUS_DSN、CHORUS_ADMIN_USERNAME、CHORUS_ADMIN_PASSWORD 和可选的精确 reset 开关；不执行迁移、seed 或 AutoMigrate。
兼容性：固定 go-admin 源码的 SysUser.Encrypt 使用裸 bcrypt；本实现使用相同的 bcrypt 默认成本，将 sys_user.role_id 绑定到已启用的 chorus_operator。固定基线没有 sys_role_user 表。
失败关闭：环境缺失、不可连接数据库、角色缺失、账号禁用/软删除/角色不匹配/空 hash 均不写入或修改管理员记录。
幂等与重置：同名正常账号默认保持 password hash；只有 CHORUS_ADMIN_RESET_PASSWORD=1 才在事务中更新。MySQL 8 测试和命令行测试均使用运行时随机构造凭据，结束后清理构造账号。
验证：go test -count=1 ./internal/adminbootstrap ./cmd/chorus-admin-bootstrap、隔离 MySQL 8 的 CHORUS_RUN_ADMIN_BOOTSTRAP_TESTS=1 go test -count=1 -v ./internal/adminbootstrap、命令行创建/重复/reset/输出脱敏检查、go build ./...、go vet ./...、go test -count=1 ./...、python dev_scripts/harness.py check --strict 和 python -m unittest discover -s tests -v 全部通过。
提交：e936144（实现与测试）、09e8601（最终 Wiki 镜像）。
长期文档：Local-Development-and-Verification revision 6ee10fcf46eda115b5d1db03f94b0ba2c0f74655；Architecture-and-Code-Map revision 8805724b04c14ef2bb5161a79a037b36e1485b68。
任务归档：Task-28-安全管理员-bootstrap-命令，revision b3d27ce84af3cc430025bae3bdb89c59b60028cd；仅保存在 Wiki，未导出 docs/task/。

验收结果（2026-08-21）

用户已明确确认 #28 验收通过；实现提交 936144 与文档提交 �9e8601 已推送。
未创建真实管理员账号，未导出 docs/task/。

文档影响

无长期文档影响。
更新项目档案或本地开发与验证：记录不含值的 bootstrap 环境变量和命令入口。
更新架构与代码地图：记录管理员 bootstrap 入口及 sys_user 与 users 的边界。

交付文档影响

无交付文档影响，原因：这是部署/运营安全初始化能力，不面向终端用户。

## 基本信息 - 类型：安全配置 - 所属 Epic：#3 - 所属 MVP / 版本：#19 / MVP-1 - 阶段：已完成 ## 原始需求 - 来源：用户对话。 - 提出时间：2026-08-21。 - 脱敏摘要：管理员账号使用 `admin`，凭据不得写入仓库；用户确认采用仓库外环境变量和一次性 bootstrap 命令的安全方案。 ## 目标与范围新增受显式调用控制的管理员 bootstrap 命令。在已完成 #20 迁移的数据库中，使用仓库外环境变量创建或维护 `sys_user` 的 `admin` 账号，并赋予 `chorus_operator` 角色。 - 账号名从 `CHORUS_ADMIN_USERNAME` 读取；部署配置把它设为 `admin`。 - 密码只从 `CHORUS_ADMIN_PASSWORD` 读取；不接受命令行密码参数，不写入代码、日志、响应、工单、Wiki、原型或测试 fixture。 - 命令默认只创建不存在账号；只有 `CHORUS_ADMIN_RESET_PASSWORD=1` 时才会重置既有账号密码。 - 使用固定 go-admin 兼容的 bcrypt 密码格式，账号状态为可登录状态；角色必须引用 `chorus_operator`，缺失时失败关闭。不新增公开注册、找回密码、管理员网页登录流程、默认密码、AutoMigrate 或生产 dev-tools。 ## 已确认方案实现独立 `cmd/chorus-admin-bootstrap`（名称可随现有命令组织微调），只通过 `CHORUS_DSN` 连接已迁移数据库。命令先验证环境、确认 `chorus_operator` 角色和目标账号的状态，再在事务中创建账号或按显式 reset 标志更新 bcrypt hash。所有输出只描述结果，不回显用户名以外的敏感配置，更不回显密码或 hash。现有管理员行被保留；不删除角色、菜单或 API 种子。#20 的迁移和用户验收是硬前置，未满足时不得开始实现。 ## 依赖与并行 - 前置工单：#20（2026-08-21 已验收通过）。 - 关联工单：#24 后续 go-admin 运营界面可复用 bootstrap 后的管理员账号。 - 是否允许并行：否；必须先确认 #20 的可逆 `sys_*` 基线。 ## 设计证据 - 类型：后端安全配置，无需 UI 原型。 - 替代设计：本工单的已确认文字方案；确认人：用户；确认时间：2026-08-21。 - 覆盖范围：外部凭据注入、显式重置、bcrypt 兼容、角色绑定、日志脱敏与失败关闭。 ## 验收标准 - [x] 缺少任一必要环境变量、DSN 不可连通、角色不存在或账号状态异常时失败关闭，且不写入账号数据。 - [x] 首次执行在已迁移的隔离 MySQL 8 中创建指定管理员账号、bcrypt hash 和 `chorus_operator` 角色绑定。 - [x] 不带 reset 开关的重复执行不修改既有 password hash；带 `CHORUS_ADMIN_RESET_PASSWORD=1` 的显式执行才更新 hash。 - [x] 命令输出、错误、测试和文档不包含密码、hash、DSN 或其他敏感值。 - [x] 受影响 Go 单元/集成测试、`go build ./...`、`go vet ./...`、`go test ./...` 通过；生产不调用 AutoMigrate。 ## 验证与回退 - 在本机隔离 MySQL 8 使用临时环境变量执行创建、重复执行、显式重置和失败路径测试；测试结束清理构造账号。 - 回退是停用或删除本次构造的管理员账号，不改变终端用户 `users`、角色种子或迁移版本；不得以回退名义删除实际管理员数据。 ## 实施记录（2026-08-21） - 实现：新增 `cmd/chorus-admin-bootstrap` 与 `internal/adminbootstrap`。命令不接受参数，只读取 `CHORUS_DSN`、`CHORUS_ADMIN_USERNAME`、`CHORUS_ADMIN_PASSWORD` 和可选的精确 reset 开关；不执行迁移、seed 或 AutoMigrate。 - 兼容性：固定 go-admin 源码的 `SysUser.Encrypt` 使用裸 bcrypt；本实现使用相同的 bcrypt 默认成本，将 `sys_user.role_id` 绑定到已启用的 `chorus_operator`。固定基线没有 `sys_role_user` 表。 - 失败关闭：环境缺失、不可连接数据库、角色缺失、账号禁用/软删除/角色不匹配/空 hash 均不写入或修改管理员记录。 - 幂等与重置：同名正常账号默认保持 password hash；只有 `CHORUS_ADMIN_RESET_PASSWORD=1` 才在事务中更新。MySQL 8 测试和命令行测试均使用运行时随机构造凭据，结束后清理构造账号。 - 验证：`go test -count=1 ./internal/adminbootstrap ./cmd/chorus-admin-bootstrap`、隔离 MySQL 8 的 `CHORUS_RUN_ADMIN_BOOTSTRAP_TESTS=1 go test -count=1 -v ./internal/adminbootstrap`、命令行创建/重复/reset/输出脱敏检查、`go build ./...`、`go vet ./...`、`go test -count=1 ./...`、`python dev_scripts/harness.py check --strict` 和 `python -m unittest discover -s tests -v` 全部通过。 - 提交：`e936144`（实现与测试）、`09e8601`（最终 Wiki 镜像）。 - 长期文档：`Local-Development-and-Verification` revision `6ee10fcf46eda115b5d1db03f94b0ba2c0f74655`；`Architecture-and-Code-Map` revision `8805724b04c14ef2bb5161a79a037b36e1485b68`。 - 任务归档：Task-28-安全管理员-bootstrap-命令，revision b3d27ce84af3cc430025bae3bdb89c59b60028cd；仅保存在 Wiki，未导出 docs/task/。 ## 验收结果（2026-08-21） - 用户已明确确认 #28 验收通过；实现提交 936144 与文档提交 �9e8601 已推送。 - 未创建真实管理员账号，未导出 docs/task/。 ## 文档影响 - [ ] 无长期文档影响。 - [x] 更新项目档案或本地开发与验证：记录不含值的 bootstrap 环境变量和命令入口。 - [x] 更新架构与代码地图：记录管理员 bootstrap 入口及 `sys_user` 与 `users` 的边界。 ## 交付文档影响 - [x] 无交付文档影响，原因：这是部署/运营安全初始化能力，不面向终端用户。

ila referenced this issue

2026-08-21 16:53:46 +08:00

mvp: MVP-1 多上游可用性与运营管理 #19

ila referenced this issue

2026-08-21 16:53:48 +08:00

epic: chorus 图文生成服务交付 #3

ila referenced this issue from a commit

2026-08-21 16:56:12 +08:00

docs: 记录安全管理员 bootstrap 工单 (#28)

ila commented

2026-08-21 17:02:57 +08:00