Files
community/docs/admin-database.md
T

225 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 管理端数据库变更 SQL
以下 SQL 由维护人员手工执行,应用不会自动迁库。已有数据库执行下面的增量 SQL;新建数据库先执行 database.md 中的四表 SQL,然后只创建本文件的任务表,不重复执行 ALTER。
执行前暂停社区端、后台和导入工具的写入并备份数据库。不要对已有列重复执行。所有时间字段由应用写入上海时间(Asia/Shanghai,UTC+8)。项目来源改为从任务表读取,因此社区端、后台和导入工具升级前都应创建任务表,即使暂不启动后台也需要执行。
## 项目字段收敛
治理相关字段为 moderation_reason(管理员下架原因)和 repo_write_status(跨进程写入状态)。下架直接使用现有 publish_status=BLOCKED,不再增加独立治理状态。GitHub来源标识、地址、默认分支和许可证属于迁移任务,统一放在 project_import_task;第一版只支持GitHub,不存平台类型,也不额外区分用户创建与后台创建。
## 已有数据库增加四类项目资源字段
在已完成原有部署的数据库中手工执行以下 SQL,再升级社区端、管理端和导入工具。新建数据库的 `database.md` 建表语句已包含这些字段,不要重复执行。
```sql
ALTER TABLE project
ADD COLUMN model_glb_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '整机GLB环境相对路径,不含域名和环境根目录',
ADD COLUMN model_glb_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0
COMMENT '整机GLB文件大小,单位字节',
ADD COLUMN model_parts_prefix VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '零件模型环境相对目录,以斜杠开头和结尾',
ADD COLUMN model_parts_files JSON NOT NULL DEFAULT (JSON_ARRAY())
COMMENT '零件GLB文件清单,包含relativePath和sizeBytes',
ADD COLUMN assembly_json_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '拼装步骤JSON环境相对路径,不含域名和环境根目录',
ADD COLUMN assembly_json_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0
COMMENT '拼装步骤JSON文件大小,单位字节',
ADD COLUMN walking_resources_prefix VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '行走资源环境相对目录,以斜杠开头和结尾',
ADD COLUMN walking_resources_files JSON NOT NULL DEFAULT (JSON_ARRAY())
COMMENT '行走资源文件清单,包含relativePath和sizeBytes';
```
路径为未编码的 `/project-resources/{projectCode}/{resourceType}/{batchCode}/{relativePath}`,不含域名和环境根目录。目录字段以 `/` 结尾,清单内路径相对于对应目录。未绑定或清除后路径为 `''`、大小为 `0`、清单为 `[]`。
Fork 直接复制这八个字段并复用原 OSS 对象,因此副本保存的路径可以包含源项目编码。读取不校验路径属于当前项目;新上传和确认只能使用当前项目的目录。替换、清除和删除项目均保留 OSS 对象,避免破坏其他副本的引用。后续如增加资源清理任务,必须检查所有项目的共享引用。
## 已有数据库增加字段
```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 '最近开始时间(Asia/Shanghai)',
finished_at DATETIME(3) NULL COMMENT '最近结束时间(Asia/Shanghai)',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
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 批次、没有后台任务的历史项目,其来源需保留原批次清单或另行归档,不能直接删除唯一来源信息。本次不对实际数据库执行增删字段操作。
## 新建普通文件写入操作记录表(本次上线前执行)
只新增此表,不需要修改项目表。由运维手工执行;应用不自动迁库。时间全部为上海时间(Asia/Shanghai,UTC+8)。
```sql
CREATE TABLE repository_write_operation (
operation_code CHAR(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL COMMENT '写入操作业务编码,同时作为幂等键',
project_code CHAR(32) NOT NULL COMMENT '项目业务编码',
repository_id BIGINT NOT NULL COMMENT '操作发起时Gitea仓库内部标识,仅核验使用',
repository_owner VARCHAR(255) NOT NULL COMMENT '操作发起时仓库所属账号',
repository_name VARCHAR(255) NOT NULL COMMENT '操作发起时仓库名称',
base_commit_sha VARCHAR(64) NOT NULL COMMENT '本次写入的基准提交SHA',
request_digest CHAR(64) NOT NULL COMMENT '请求内容SHA256摘要,不保存文件正文',
commit_message VARCHAR(1000) NOT NULL COMMENT '原始提交说明,不包含系统凭据尾注',
status VARCHAR(16) NOT NULL COMMENT '操作状态 PROCESSING处理中 NEEDS_REVIEW超时待确认 SUCCEEDED已成功 FAILED明确失败',
result_commit_sha VARCHAR(64) NULL COMMENT '确认成功的提交SHA',
failure_status INT NULL COMMENT '明确失败时原HTTP状态码',
last_error_code VARCHAR(64) NULL COMMENT '最近核对错误编码,不保存异常正文或凭证',
check_count INT NOT NULL DEFAULT 0 COMMENT '后台已执行核对次数',
next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间(Asia/Shanghai)',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间(Asia/Shanghai)',
PRIMARY KEY (operation_code),
KEY idx_write_project_status (project_code, status, created_at),
KEY idx_write_next_check (status, next_check_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='普通文件写入幂等凭据及自动核对记录';
```
已完成的操作记录仍用于幂等重放,不要在客户端可能重试期间删除。历史 REVIEW 没有操作记录,不会凭最新 SHA 自动判成功;需核对实际结果后按原维护流程处理。迁移、Fork 继续使用原流程。
## 业务时间由 UTC 迁移到上海时间
新版统一通过 `ProjectSupport` 生成上海时间(`Asia/Shanghai`),字段类型保持 `DATETIME(3)`。以下 SQL 由维护人员手工执行,应用不会执行迁移,也不会自动修改已有数据库。
执行顺序:暂停社区端、管理端和导入工具,备份业务数据库及导入状态目录;确认以下六张表中的历史时间仍全部为 UTC 后执行一次转换;核对结果后同时部署新版各模块,并同步前端的 `+08:00` 解析方式,再恢复服务。新建空库无需执行数据转换。若已经写入上海时间或存在混合时区数据,必须先按切换记录确定待转换数据范围,不能直接执行以下全表更新;本脚本不能重复执行。
```sql
USE vibemake;
START TRANSACTION;
UPDATE sys_user
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR);
UPDATE project
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
published_at = DATE_ADD(published_at, INTERVAL 8 HOUR);
UPDATE project_comment
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR);
UPDATE project_like
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR);
UPDATE project_import_task
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
started_at = DATE_ADD(started_at, INTERVAL 8 HOUR),
finished_at = DATE_ADD(finished_at, INTERVAL 8 HOUR);
UPDATE repository_write_operation
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
next_check_at = DATE_ADD(next_check_at, INTERVAL 8 HOUR);
COMMIT;
```
空值保持为空,毫秒精度保持不变。`next_check_at` 等调度时间也需要转换,避免切换后提前或延后核对任务。Git 提交日期、OSS 签名内容和 Gitea 内部数据库不参与转换。
已有数据库的时间字段注释可单独按以下 SQL 更新;DDL 会隐式提交,不要放入上面的数据转换事务。
```sql
ALTER TABLE sys_user
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)';
ALTER TABLE project
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
MODIFY COLUMN published_at DATETIME(3) NULL COMMENT '最近发布时间(Asia/Shanghai)';
ALTER TABLE project_comment
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)';
ALTER TABLE project_like
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '点赞时间(Asia/Shanghai)';
ALTER TABLE project_import_task
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
MODIFY COLUMN started_at DATETIME(3) NULL COMMENT '最近开始时间(Asia/Shanghai)',
MODIFY COLUMN finished_at DATETIME(3) NULL COMMENT '最近结束时间(Asia/Shanghai)';
ALTER TABLE repository_write_operation
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间(Asia/Shanghai)',
MODIFY COLUMN next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间(Asia/Shanghai)';
```
旧导入状态首次由新版读取时,将未声明时区的 `reservedAt` 从 UTC 转为上海时间,原子保存并标记 `timeZone=Asia/Shanghai`,后续不会再次转换。应在业务库完成转换后再续跑;未迁移的数据库时间与清单不一致时,现有归属校验会阻止接管项目。回滚应用前需要同时恢复数据库和导入状态备份,并恢复前端的旧时间解析约定。