# 管理员账号与关闭注册

2026-10-05：新增 `User.role`、`User.banned`、`User.mustChangePassword`，迁移 `20261005130000_admin_accounts`。现有用户保留 `user`、未封禁、无需首次改密；初始化管理员和新创建账号强制首次改密。

配置位于 `apps/api/.env`：

```dotenv
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin
```

初始化仅在数据库没有管理员时执行，不覆盖同名账号，不重置已存在管理员。账号名冲突时配置其他用户名再重启。公开注册接口返回 403，登录页面移除注册入口。初始密码允许 `admin`，新密码使用原有强密码校验，且不能与初始密码相同。未改密时只有个人身份、改密、活动和退出接口可访问；业务接口、后台和 MCP 授权被拒绝。

后台接口：`GET /api/admin/users?limit=50&offset=0`、`POST /api/admin/users`、`PATCH /api/admin/users/:id`。列表完整分页，仅返回账号身份、角色、状态和创建时间；不返回哈希、会话令牌或财务数据。角色为 `admin`、`user`、`readonly`。管理动作在事务内重查管理员权限；禁止修改自身角色或封禁自己，并保留可用管理员。

删除原管理员：先创建或设置另一位管理员，使用新管理员登录并完成首次改密，然后在后台默认 admin 所在行点击“删除默认 admin”。输入被删除账号名称和当前管理员密码后确认。`DELETE /api/admin/users/:id` 仅允许删除名为 admin 且角色为管理员的默认账号，其他账号禁止删除；后端在事务中重查操作人权限、密码是否变化、被删除用户名和剩余管理员状态。至少保留另一位未封禁且完成改密的管理员，不允许删除自己。默认账号改名后也不显示删除入口。删除不可撤销，会级联清理该账号财务数据、会话和 MCP 授权，并删除私有图标；已发布共享图标保留。仍有其他管理员时，重启不会重新创建默认 admin。

角色/封禁状态变化会删除该用户全部会话、撤销 MCP/PAT/OAuth 授权、取消待确认草稿和已批准待兑换授权。解封不会恢复旧令牌。密码修改也会撤销既有 MCP 授权。HTTP 与 MCP 后端都会检查封禁、首次改密和只读权限；只读用户可管理自己的登录密码及只读连接，无法提交财务写入、草稿或确认业务操作。管理员仍遵循原有财务数据用户隔离。

验证：前后端类型检查、网页生产构建、53 项单元测试，以及使用临时 MySQL 库和独立 API 的管理员与现有业务/MCP/OAuth 回归。当前数据库已应用新增迁移；本机网页验证默认管理员首次登录展示强制改密页，未替用户设置新密码。

追加验证：新管理员首次改密后删除原 admin 成功，用户名确认或密码错误时拒绝，普通用户和未改密管理员无权删除，禁止删除当前管理员。被删除用户的持仓、历史、私有图标和授权被清理，共享图标保留，新管理员仍可使用后台；再次初始化不会重建原账号。图标表通过 `20261005150000_remove_icon_source` 移除 source，接口、前端类型和图标初始化脚本同步调整，现有 ZIP v9 图标格式保持一致。53 项单元测试与 29 项隔离回归通过。

运行隔离回归：在仓库根目录执行 `pnpm --filter @worthpath/api test:isolated`。测试库名使用随机 `wp_test_` 前缀，API 使用随机本机端口；完成或失败后清理自己创建的服务和数据库。管理员测试只在该隔离流程中运行，避免修改真实管理员。

历史 `005_account_icons`、`006_navigation_transfers`、`007_notes_display` 排在初始迁移之前的问题已由项目迁移入口修复，保留所有历史目录名称和 SQL 校验值。隔离测试通过正式迁移入口建立空库，再运行业务回归；不再使用 `db push` 或手动改列来代替迁移。空库失败恢复与部署命令见 [数据库迁移](database-migrations.md)。

2026-10-05 补充修复：删除按钮仅对默认 admin 显示，后端同时限制账号名称与管理员角色。普通用户、只读用户和非默认管理员均不能被删除，即使由管理员直接请求接口也拒绝；这些拒绝不会改变账号、会话、财务数据和授权。默认 admin 删除及保留可用管理员的保护继续通过隔离回归，详见 [更新验收](update-connections-repayment-users-2026-10-05.md)。