Files
community/docs/admin-database.md
T

88 lines
7.3 KiB
Markdown

# 管理端数据库变更 SQL
以下 SQL 由维护人员手工执行,应用不会自动迁库。已有数据库执行下面的增量 SQL;新建数据库先执行 database.md 中的四表 SQL,然后只创建本文件的任务表,不重复执行 ALTER。
执行前暂停社区端、后台和导入工具的写入并备份数据库。不要对已有列重复执行。所有时间字段由应用写入 UTC。项目来源改为从任务表读取,因此社区端、后台和导入工具升级前都应创建任务表,即使暂不启动后台也需要执行。
## 项目字段收敛
project 只新增 moderation_reason(管理员下架原因)和 repo_write_status(跨进程写入状态)两个字段。下架直接使用现有 publish_status=BLOCKED,不再增加独立治理状态。GitHub来源标识、地址、默认分支和许可证属于迁移任务,统一放在 project_import_task;第一版只支持GitHub,不存平台类型,也不额外区分用户创建与后台创建。
## 已有数据库增加字段
```sql
ALTER TABLE sys_user ADD COLUMN role VARCHAR(16) NOT NULL DEFAULT 'USER' COMMENT '用户角色 USER普通用户 ADMIN管理员 OFFICIAL官方托管账号';
ALTER TABLE sys_user ADD COLUMN password_hash VARCHAR(100) NULL COMMENT '管理员BCrypt密码哈希,普通用户为空';
ALTER TABLE sys_user ADD COLUMN session_version BIGINT NOT NULL DEFAULT 0 COMMENT '登录会话版本,禁用或修改密码时递增';
ALTER TABLE project MODIFY COLUMN publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '发布状态 UNPUBLISHED未发布 PUBLISHED已发布 BLOCKED管理员下架';
ALTER TABLE project ADD COLUMN moderation_reason VARCHAR(500) NULL COMMENT '管理员下架原因';
ALTER TABLE project ADD COLUMN repo_write_status VARCHAR(16) NOT NULL DEFAULT 'IDLE' COMMENT '仓库写入状态 IDLE空闲 WRITING写入中 REVIEW待核对';
```
## 新建迁移任务表
```sql
CREATE TABLE project_import_task (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部任务主键',
task_code CHAR(32) NOT NULL COMMENT '迁移任务业务编码',
project_code CHAR(32) NOT NULL COMMENT '目标项目业务编码',
operator_user_code CHAR(32) NOT NULL COMMENT '任务创建管理员用户编码',
source_repository_id BIGINT NOT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用',
source_repository_url VARCHAR(2048) NOT NULL COMMENT 'GitHub仓库规范公开地址',
source_default_branch VARCHAR(255) NOT NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验',
source_license VARCHAR(128) NULL COMMENT 'GitHub许可证标识,无法识别时为空',
status VARCHAR(16) NOT NULL DEFAULT 'QUEUED' COMMENT '任务状态 QUEUED排队 RUNNING执行 SUCCEEDED成功 FAILED失败 REVIEW待核对',
phase VARCHAR(32) NOT NULL DEFAULT 'QUEUED' COMMENT '迁移阶段 QUEUED CLEANING PRECHECK MIGRATING MIGRATED NORMALIZING BRANCH_READY LINKED',
receipt_json TEXT NULL COMMENT '已确认迁移完成收据JSON,仅内部使用,不包含认证凭据',
target_sha VARCHAR(64) NULL COMMENT '迁移后冻结的目标提交SHA',
error_code VARCHAR(64) NULL COMMENT '最近失败错误码',
warnings_json TEXT NOT NULL COMMENT '兼容性提醒JSON数组',
started_at DATETIME(3) NULL COMMENT '最近开始时间UTC',
finished_at DATETIME(3) NULL COMMENT '最近结束时间UTC',
created_at DATETIME(3) NOT NULL COMMENT '创建时间UTC',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间UTC',
PRIMARY KEY (id),
UNIQUE KEY uk_import_task_code (task_code),
UNIQUE KEY uk_import_project (project_code),
UNIQUE KEY uk_import_source (source_repository_id),
KEY idx_import_queue (status, created_at),
CONSTRAINT fk_import_project FOREIGN KEY (project_code) REFERENCES project(project_code),
CONSTRAINT fk_import_operator FOREIGN KEY (operator_user_code) REFERENCES sys_user(user_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='后台公开GitHub项目迁移任务';
```
没有管理员账号表、管理员会话表、审计表或仓库状态表。第一位管理员使用初始化命令设置,禁止手写明文密码入库。后续手工修改角色时必须同时递增 session_version,且 ADMIN 必须具有通过 BCrypt 编码的密码。官方托管账号由后台首次创建或迁移项目时自动建立,保留邮箱为 vibemake-official@internal.invalid。
REVIEW 或遗留 WRITING 不应直接改为 IDLE:先核对 Gitea 写入、迁移收据、LFS 完成情况、仓库身份及提交。已持久化成功收据时提供只读核对后的续跑;明确 GITEA_MIGRATION_REJECTED 的任务允许通过 retry 进入 CLEANING,核验并清理归属于该任务的失败仓库后重迁。清理身份使用现有 project.gitea_repo_id 保存,保留原任务与项目,不新增字段或表。已有 phase 为 VARCHAR,无需因新增 CLEANING 阶段执行数据库变更。不提供强制成功操作。
## 已经执行过上一版管理端 SQL 的数据库
本节只供已经存在旧字段/旧任务表的数据库手工升级;尚未执行旧版 SQL 的数据库不要执行本节。先暂停写入并备份,不自动删除旧字段。
```sql
ALTER TABLE project_import_task ADD COLUMN source_repository_id BIGINT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用';
ALTER TABLE project_import_task ADD COLUMN source_repository_url VARCHAR(2048) NULL COMMENT 'GitHub仓库规范公开地址';
ALTER TABLE project_import_task ADD COLUMN source_default_branch VARCHAR(255) NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验';
ALTER TABLE project_import_task ADD COLUMN source_license VARCHAR(128) NULL COMMENT 'GitHub许可证标识,无法识别时为空';
UPDATE project_import_task t JOIN project p ON p.project_code = t.project_code
SET t.source_repository_id = p.external_repository_id,
t.source_repository_url = p.external_repository_url,
t.source_default_branch = p.external_default_branch,
t.source_license = p.external_license;
-- 检查结果必须为空,才能把三个必需来源字段设为 NOT NULL。
SELECT task_code, project_code FROM project_import_task
WHERE source_repository_id IS NULL OR source_repository_url IS NULL OR source_default_branch IS NULL;
ALTER TABLE project_import_task MODIFY COLUMN source_repository_id BIGINT NOT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用';
ALTER TABLE project_import_task MODIFY COLUMN source_repository_url VARCHAR(2048) NOT NULL COMMENT 'GitHub仓库规范公开地址';
ALTER TABLE project_import_task MODIFY COLUMN source_default_branch VARCHAR(255) NOT NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验';
ALTER TABLE project_import_task ADD UNIQUE KEY uk_import_source (source_repository_id);
UPDATE project SET publish_status = 'BLOCKED' WHERE moderation_status = 'BLOCKED' AND deleted = 0;
ALTER TABLE project MODIFY COLUMN publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '发布状态 UNPUBLISHED未发布 PUBLISHED已发布 BLOCKED管理员下架';
```
旧版七个字段及其索引可以暂留,代码已不再读写;确认备份及来源回填完成后再清理。特别是只有旧 Excel 批次、没有后台任务的历史项目,其来源需保留原批次清单或另行归档,不能直接删除唯一来源信息。本次不对实际数据库执行增删字段操作。