Files
community/docs/admin-deployment.md
T

7.0 KiB
Raw Blame History

Community 管理端部署与运维

管理端为独立 Spring Boot 应用 community-adminapi,默认端口 8994,接口前缀 /admin-api。项目文件复用现有 Gitea 私有组织仓库,封面与 URDF 复用 OSS;不需要新建 Gitea 账号或组织。前端对接见 管理后台接口文档。

部署与初始化

  1. 备份数据库、暂停写入、排空旧进程。已有数据库手工执行 增量 SQL,新数据库先执行 基础四表 SQL,再创建迁移任务表。应用不自动执行 SQL。社区端也会读取迁移任务,因此暂不启用管理端时仍需创建该表。
  2. 更新社区端、管理端和 Excel 导入工具,确保全部写入端使用数据库共享锁。
  3. 在 .env 或部署环境中提供现有 DB_*、GITEA_*、OSS_*;后台默认关闭 AI。默认环境为 test,正式部署显式设置 SPRING_PROFILES_ACTIVE=prod。真实 .env 不提交,不用示例覆盖已有凭据。
  4. 选择一个已有、正常的普通用户,执行初始化命令,交互输入两次管理员密码。密码至少 12 字符、UTF-8 最多 72 字节,不会写入命令参数或日志。该命令只初始化 USER,不用于重置已有管理员密码;成功后进程退出。
  5. 正常启动管理端,配置前端代理或后台跨域来源。第一版两个应用分别单实例运行,不能通过负载均衡随机分发同一应用的登录会话。
bash scripts/run-admin-local.sh --bootstrap-admin-user-code='<已有用户编码>'
bash scripts/run-admin-local.sh

如仅初始化管理员、当前没有 OSS 凭据,可以传 --community.oss.enabled=false。直接运行 jar 时不会自动读取 .env,必须先在部署环境提供连接变量。本地脚本以 ADMIN_SERVER_PORT 设置后台端口,避免共用 .env 中的社区 SERVER_PORT 覆盖;直接部署时也应避免传入社区端的 SERVER_PORT。

SPRING_PROFILES_ACTIVE=prod java -jar community-adminapi/target/community-adminapi-0.0.1-SNAPSHOT.jar
配置 默认值/说明
ADMIN_SERVER_PORT 8994;独立于社区端 SERVER_PORT
ADMIN_ALLOWED_ORIGINS 空;完整前端来源用英文逗号分隔,不使用通配符
ADMIN_IMPORT_WORKER_ENABLED true;维护期间可关闭消费
ADMIN_IMPORT_CONCURRENCY 2,范围 1~4
ADMIN_MIGRATION_TIMEOUT 30m,仅迁移请求使用,普通 Gitea 超时不变
GITHUB_TOKEN 可选,只访问 GitHub 元数据 API,不能填写 Gitea Token
community.token-ttl 后台默认 8h,可通过 Spring 配置覆盖

日志为 community-adminapi.log 和 community-adminapi-error.log,沿用 requestId、归档和脱敏规范。写操作记录实际操作用户编码、目标编码、接口动作、HTTP 结果和耗时;关键项目与迁移步骤另有业务日志。

账号与权限

复用 sys_user:USER 普通用户、ADMIN 管理员、OFFICIAL 官方托管账号。后台必须同时验证邮箱、密码、正常状态和 ADMIN 角色。管理员及官方账号不允许通过社区无密码入口登录,两个应用的本机 Token 不互通。后台重启后需要重新登录。

每次请求检查角色、状态和会话版本。禁用、修改密码或手工变更角色并递增 session_version 后,旧 Token 失效;恢复状态不会恢复旧会话。第一版无角色修改接口。

连续登录失败按账号 5 次、来源地址 30 次限速,15 分钟后重试;只使用连接来源地址,不信任任意客户端提交的转发 IP 头。

项目不指定归属用户时,自动创建或复用官方账号,保留邮箱 community-official@internal.invalid。该地址在账号建立前也禁止社区登录。若已有账号的角色或状态异常,停止创建并人工核对,不接管普通用户。

仓库写入与迁移

project 表只新增 moderation_reason 和 repo_write_status,来源标识、地址、默认分支和许可证保存在 project_import_task。成功迁移任务用于项目来源展示与去重,不能按普通日志过期删除。Excel 运维导入仍通过原批次清单保留来源,不伪造后台任务。

全部写入端按项目编码取得同一 MySQL 命名锁,使用固定连接取得、持有和释放,支持内部重入。锁连接池每应用最多 8 个连接,另有普通业务连接池,需要预留数据库容量。远端请求期间不持有数据库长事务;写入前持久化状态,结果不明时重启后仍阻断写入。

上线前确认目标 Gitea 已开启迁移、HTTP Git、LFS,技术账号具有组织仓库写权限。GitHub 预检优先读取 API;受限时严格核对公开网页身份、可见性和默认分支,无法确认时失败。网页回退拿不到的简介、许可证可能为空,需要管理员检查原仓库文件。

迁移成功收据先持久化,再处理分支、关联和就绪状态。迁移保留 Git 历史、分支、标签并请求迁移 LFS;不导入 Issue、PR、Wiki、Release 附件,不递归复制子模块或外链。原默认分支不是 main 时补建 main;已有 main 与源默认分支内容不同则停止,不覆盖。

迁移表单支持预上传封面及 URDF。URDF 使用现有 OSS 配置与限额,创建任务前检查对象,并使用 project 既有 URDF 字段保存,不需要新增数据库变更。上传后未提交表单的 OSS 对象不会自动清理,沿用现有资源生命周期。

异常核对

  • 超时、进程在 MIGRATING 阶段中断或远端结果不明确时进入 REVIEW。禁止自动重发,也不能仅凭仓库存在判定成功。
  • REMOTE_RESULT_UNKNOWN 需要按 requestId、项目编码、任务编码核对日志和 Gitea,不应删除目标仓库后直接重跑。
  • 已持久化成功收据且停在 MIGRATED 的任务,retry 会只读验证仓库身份、来源等后续跑。
  • 停在 NORMALIZING/BRANCH_READY 且有冻结目标 SHA 的任务,retry 会核对已适配分支和收据后续跑;验证不通过继续阻断。
  • 无强制成功、直接清除未知写入状态、任务取消接口。不能直接把 REVIEW 改成成功。
  • 迁移成功不自动发布,先在 test 验证单个仓库及人工发布,再开放生产入口。
  • 停用后台先关闭任务消费、排空正在执行的任务,再停止应用。不要在后台或 Excel 导入仍写入时回退社区端到旧写入逻辑。

逻辑删除、撤回和下架不会物理删除 Gitea 仓库或 OSS 对象;已公开 OSS 链接沿用现有生命周期。

验证

AI_ENABLED=false OSS_ENABLED=false mvn clean verify
bash scripts/test-admin-mysql.sh

普通测试使用 H2 和模拟 GitHub/Gitea/OSS,不访问现有业务库或真实仓库。真实 MySQL 测试使用 .env 的 DB_* 或 ADMIN_MYSQL_TEST_* 连接配置,只创建/删除随机 community_admin_verify_* 临时库;需要创建临时库权限。验证跨实例互斥、重入、持久化阻断、断开持锁连接及新进程恢复,不对已有业务库执行 DDL。