Files
community/docs/admin-deployment.md
T

22 KiB
Raw Blame History

Vibemake 管理端部署与运维

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

部署与初始化

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

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

SPRING_PROFILES_ACTIVE=prod java -jar vibemake-adminapi/target/vibemake-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
vibemake.token-ttl 后台默认 8h,可通过 Spring 配置覆盖

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

账号与权限

复用 sys_user:USER 普通用户、ADMIN 管理员、OFFICIAL 官方托管账号。后台必须同时验证邮箱、密码、正常状态和 ADMIN 角色。管理员及官方账号不允许通过社区无密码入口登录,两个应用的 Redis Key 域隔离、Token 不互通。应用重启后保留未过期会话。

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

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

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

仓库写入与迁移

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

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

普通文件上传和编辑使用 repository_write_operation 持久化幂等凭据。正常为 IDLE → WRITING → IDLE;响应丢失先尝试只读匹配凭据,匹配成功仍返回 200。未知结果持久化 REVIEW,保持原有错误响应,由后台每 15 秒核对,10 分钟后改为每分钟继续核对。核对成功自动恢复 IDLE,不自动发布。提交前或发布前的 Gitea 读取失败保持 IDLE,不能误标为未知写入。操作编码由后端自动生成,前端不需要改造。

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

失败迁移重试需要技术账号及 Token 具有目标私有仓库读取、迁移创建及删除权限。后台迁移时在 Gitea 仓库描述中写入任务归属标识;不要手工修改该标识。它仅用于失败仓库清理核验,不改变社区项目的名称和描述。

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

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

异常核对

  • 超时、进程在 MIGRATING 阶段中断或远端结果不明确时进入 REVIEW。禁止自动重发,也不能仅凭仓库存在判定成功。
  • Gitea 明确返回 GITEA_MIGRATION_REJECTED 时显示 FAILED,提供重试。原有同错误的 REVIEW 任务也可申请重试;后台持有项目共享锁,在 CLEANING 阶段核验任务标识、组织、名称、来源及已记录的仓库 ID,清理后确认不存在再迁移。没有残留仓库时直接继续,不删除项目记录或 OSS 资源。
  • 清理操作写入前持久化 CLEANING 阶段及仓库身份;删除超时或数据库回写失败时保持阻断,下次重试先核验是否已删除再继续。仓库已替换、来源不符、缺少任务归属标识时不删除;旧任务的无标识残留仓库仍需人工核对。已就绪、发布过的项目及已有成功收据的迁移不会走删除重迁流程。
  • 人工核对后已删除目标仓库的任务,可在原任务页刷新并重试,无需修改状态或清空仓库 ID。后台重新确认仓库不存在后才清除旧仓库关联和写入阻断,保留原项目与资源继续迁移;再次点击不能绕过仍存在仓库的身份校验。
  • REMOTE_RESULT_UNKNOWN 需要按 requestId、项目编码、任务编码核对日志和 Gitea,不应删除目标仓库后直接重跑。
  • 已持久化成功收据且停在 MIGRATED 的任务,retry 会只读验证仓库身份、来源等后续跑。
  • 停在 NORMALIZING/BRANCH_READY 且有冻结目标 SHA 的任务,retry 会核对已适配分支和收据后续跑;验证不通过继续阻断。
  • 无强制成功、直接清除未知写入状态、任务取消接口。不能直接把 REVIEW 改成成功。
  • 迁移成功不自动发布,先在 test 验证单个仓库及人工发布,再开放生产入口。
  • 停用后台先关闭任务消费、排空正在执行的任务,再停止应用。不要在后台或 Excel 导入仍写入时回退社区端到旧写入逻辑。

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

普通项目后台自动核对

上线顺序:手工执行 操作表 SQL → 排空旧写入进程 → 同时升级社区 API 与管理 API。接口沿用原有请求及成功/错误响应,不新增 202、前端结果查询或在线恢复接口。前端不需要接入新协议。

后台任务在两个 API 应用中默认启动,由数据库项目命名锁避免重复核对;在独立线程执行,避免阻塞迁移任务调度。vibemake.repository-write.worker-enabled=false 可停用本实例的核对消费,但必须至少保留一个启用的实例。操作记录在远端写入前落盘,进程重启后按 next_check_at 继续;结果未知只查不重发。每次扫描 main 可达的最近至多 1000 个提交,精确校验操作尾注、请求摘要、唯一父提交及仓库身份;超范围、读取失败或不匹配均保留未知,不自动判失败。

前 10 分钟每 15 秒核对,超过 10 分钟改为每分钟继续核对,不强制解除保护。使用 projectCode、operationCode、baseCommitSha、commitSha、checkCount、errorCode 关联日志;原始请求正文和认证信息不进入操作表。操作状态 PROCESSING 为处理中,NEEDS_REVIEW 为超过 10 分钟仍未确认,SUCCEEDED 为确认成功,FAILED 为明确拒绝。操作终态与 IDLE 在同一事务确认;其他实例下次取得共享锁时按数据库结果清除旧内存标记,无需重启。

上传或编辑超时后如果立即查到凭据,原接口直接返回 200;暂时不能确认时仍返回原错误,不会把本次上传显示为成功。后台确认后自动恢复写入,管理员刷新工作区后即可继续。未确认期间禁止新的远端写入,重试不自动重发 Gitea POST。恢复不会自动发布。

历史 REVIEW/遗留 WRITING 没有操作记录时不做自动猜测,仍需核对仓库身份、文件、历史和上次操作是否已结束,再按原维护流程处理。迁移和 Fork 继续使用原专门核验流程。本阶段暂不提供管理员在线恢复入口。

验证

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_* 连接配置,只创建/删除随机 vibemake_admin_verify_* 临时库;需要创建临时库权限。验证跨实例互斥、重入、持久化阻断、断开持锁连接及新进程恢复,不对已有业务库执行 DDL。

Redis 安全与资源保护

本版本采用 Redis 8.10.2 单节点直连,两个在线应用各单实例。首次部署时停止并排空旧进程再替换,新旧会话存储不混用;旧本机会话和验证码不会迁移,需重新登录一次。应用重启可保留 Redis 中未过期的会话,Redis 自身重启能否保留取决于服务器持久化配置。回退旧版本需要重新登录,不执行 Redis 全库清理,遗留 Key 按 TTL 过期。本次无数据库迁移。

连接与隔离

环境变量 默认值与用途
REDIS_HOST / REDIS_PORT test 为 localhost / 6379;prod 主机必须显式配置
REDIS_USERNAME / REDIS_PASSWORD 用户名可选;prod 密码必须显式配置,不将凭据放进连接 URL
REDIS_DATABASE 0,两个应用可使用同一逻辑库
REDIS_SSL_ENABLED false;启用时使用 JVM 信任库验证服务端证书,不关闭证书验证
REDIS_CONNECT_TIMEOUT / REDIS_TIMEOUT 2s / 1s
REDIS_KEY_PREFIX test 为 vibemake:test,prod 为 vibemake:prod;随后追加 api:v1: 或 admin:v1:
TRUSTED_PROXY_CIDRS 空,默认不信任转发头;实际反向代理 IP/CIDR 用逗号分隔

相同环境的应用重启必须沿用相同前缀;不同环境使用不同前缀和凭据范围。配置可信代理后,从连接来源开始由右向左剥离可信代理链,使用首个不可信地址限流;不信任任意客户端提交的 X-Forwarded-For。后端入口应只允许部署代理访问,代理需覆盖或正确追加转发链。不要同时在容器层无条件改写 remoteAddr,否则会绕过应用对代理来源的判断。

在线启动探测 SET NX PX、GET、GETDEL、计数 Lua、TTL 和 DEL;拒绝权限不足或连接异常的启动。运行期间 Redis 故障返回 503 REDIS_UNAVAILABLE,不回退本机或放行。离线导入和 bootstrap-admin-user-code 命令不执行 Redis 探测。

权限与运行配置

为应用配置仅能访问自己环境前缀的 Redis ACL 用户。业务命令为 GET、SET、GETDEL、DEL、TTL、INCR、PEXPIRE、PTTL、EVAL、EVALSHA;Lettuce 连接还需 AUTH/HELLO、PING、SELECT(非零逻辑库)、CLIENT SETNAME/SETINFO。按服务端 ACL 语法授予这些命令和对应 ~vibemake:prod:api:v1:* / ~vibemake:prod:admin:v1:* Key 范围,或为两端共用账号授权两段范围。无需 FLUSHDB、FLUSHALL、KEYS、CONFIG、ACL 或通用管理权限。集成测试的随机测试前缀额外需要 SCAN,生产应用不执行扫描。

Redis 只监听内网或回环地址,启用认证;跨不可信网络使用 TLS。容量监控包括 used_memory、拒绝写入、evicted_keys、连接错误和延迟。安全状态应有独立容量保障,推荐专用实例使用 noeviction 和合适的 maxmemory,避免普通缓存淘汰会话或限流计数;noeviction 内存耗尽时写入失败,应用返回 503,需容量告警。持久化按业务要求配置并验证重启恢复,不能把会话当作可随意淘汰的普通缓存。应用不会自动修改既有 Redis 全局配置。

频率与大小配置

固定窗口从该主体第一次调用时开始,持续 60 秒;按请求尝试计数,繁忙和失败也计入,窗口内不会因再次调用滑动延长。用户操作在业务入口限流,覆盖 AI 和 HTTP;管理员按操作管理员身份计数。各行独立,文件提交/上传以及点赞/取消点赞各自共享所在行额度。

环境变量 默认次数/分钟 主体
RATE_CAPTCHA_PER_MINUTE 20 IP
RATE_LOGIN_IP_PER_MINUTE 20 IP
RATE_LOGIN_ACCOUNT_PER_MINUTE 10 规范化邮箱
RATE_ADMIN_LOGIN_PER_MINUTE 30 IP,另保留失败次数限制
RATE_VIBEMAKE_READ_PER_MINUTE 120 IP
RATE_FILE_READ_PER_MINUTE 60 IP
RATE_CREATE_PER_MINUTE 5 用户/操作管理员
RATE_FORK_PER_MINUTE 10 用户/操作管理员
RATE_FILE_WRITE_PER_MINUTE 10 用户/操作管理员
RATE_COVER_SIGN_PER_MINUTE 30 用户/操作管理员
RATE_URDF_SIGN_PER_MINUTE 20 用户/操作管理员
RATE_COMMENT_PER_MINUTE 10 用户
RATE_LIKE_PER_MINUTE 60 用户

超限为 429 RATE_LIMITED,保留 AI_RATE_LIMITED、AI_BUSY、FORK_BUSY、ADMIN_LOGIN_LIMITED 等现有代码。普通限流响应带 Retry-After(秒),其响应体 data.retryAfterSeconds 同步提供剩余等待时间。后台失败限制维持账号 5 次/IP 30 次,失败记录在最后一次失败后 15 分钟过期;成功仅清理对应账号失败次数。应用仅聚合记录同一规则的限流日志,不记录邮箱或 Token。

配置 默认值
HTTP_JSON_MAX_BYTES 262144,普通 JSON 256 KiB
HTTP_URDF_JSON_MAX_BYTES 2097152,URDF 清单 2 MiB
HTTP_COMMIT_JSON_MAX_BYTES 67108864,提交 JSON 64 MiB
FILE_MAX_CONCURRENT 4,单实例文件读取/目录/历史/提交/multipart 处理名额
FORK_MAX_CONCURRENT 2,保持独立 Fork 执行名额

JSON 上限为实际线上请求字节数,包含转义和结构开销;业务单文件/总内容上限继续保留。Content-Length 和 chunked 均流式核验,超限返回 413 REQUEST_TOO_LARGE。仓库上传单文件最多 50 MiB、文件合计最多 200 MiB、每批最多 500 个文件,multipart 整个请求最多 202 MiB(预留 2 MiB 表单开销),原有 UPLOAD_TOO_LARGE/FILE_TOO_LARGE 错误保留;部署反向代理时同步确保请求体上限不低于 202 MiB。URDF 直传 OSS 不占用这类 multipart 名额。文件名额不足为 429 FILE_BUSY,不排队;Fork 繁忙仍为 FORK_BUSY。

API 和管理端均显式配置 server.tomcat.max-part-count=1003,允许 500 个 files、500 个 paths 及 3 个公共字段。Tomcat 默认的 50 项无法承载业务允许的批量上传;数量超限会被 Spring 包装成上传大小异常,现区分为 413 UPLOAD_TOO_MANY_PARTS 并记录安全诊断日志。部署时若覆盖该配置,需要与业务批量文件数对齐。

Gitea 原始文件有界读取,contents JSON 上限按单文件 Base64 膨胀量加 2 MiB 元信息计算,其他元数据 8 MiB,错误响应 64 KiB。GET 超限返回 502 GITEA_RESPONSE_TOO_LARGE;写入响应无法完整确认仍为 REMOTE_RESULT_UNKNOWN,持久化阻断后续仓库写入,不自动重试。

依赖安全核对(2026-10-22)

基线升级为 Boot 3.5.16、Security 6.5.11、Framework 6.2.19、Tomcat 10.1.61,保持 Java 21;Redis/Lettuce 由 Boot BOM 管理。以下为本次针对实际使用路径的公告核对,不等同于全量依赖扫描或账号安全问题已解决。

公告 条件与本项目处理
CVE-2026-22732 安全响应头在特定写出路径缺失;Security 升至 6.5.11,超过该问题最低修复版 6.5.9,验证登录、下载及错误响应缓存头
CVE-2026-22735 SSE 非结构化文本且攻击者控制发给其他用户的内容;Framework 已超过最低修复版 6.2.17,应用也使用 JSON 结构化事件
CVE-2026-24880 特定代理放过异常 HTTP/1.1 chunk 扩展时可请求走私;Tomcat 10.1.61 含修复,代理仍应严格校验请求
CVE-2026-101356 Tomcat 10.1.55~10.1.60 的 HTTP/2 异步请求/响应复用问题;显式锁定 10.1.61,避免使用 Boot BOM 默认的 10.1.55
CVE-2026-47883 UrlHandlerFilter 使用过宽匹配模式时的开放重定向;仓库未使用该 Filter,本次记录为条件风险,后续引入该组件前重新核对修复版本

依据:Spring 响应头公告、Spring SSE 公告、Spring UrlHandlerFilter 公告、Tomcat 公告、Boot 依赖版本。普通用户邮箱冒名登录按本次范围保留,后续更换登录方式时单独处理。

生产两端必须配置同一个目标 GITEA_ORGANIZATION;prod 关闭 Swagger/OpenAPI,test 保留。AI、OSS 默认关闭并需显式启用;不增加数据库迁移。部署后验证 Redis 隔离、应用重启会话、禁用失效、限流、大小保护、Gitea 写入结果不明状态和公开 GET 行为,再开放流量。

验证记录与性能基准(2026-10-22)

已通过真实 Redis 8.10.2 的 TTL、原子消费、原子计数、域隔离、重建连接、撤销和账号禁用验证,以及真实 MySQL 的共享锁、重入、持久化阻断和持锁连接断开测试。全部数据库验证只创建/删除随机临时库,Redis 测试只使用随机前缀,未改动既有业务表或 Redis 全局配置。

基准使用改造前 HEAD 的独立源码副本与当前版本,固定 JDK 21、JVM 堆 128~512 MiB、21 个项目、20 个用户、20 条评论、20 条导入来源,每次读取 20 条,预热后每场景 100 次调用,前后按顺序运行。MySQL 使用两个独立随机临时库,测试结束删除。SQL 数为服务层物理 SELECT 数,不包含 HTTP 安全过滤器的账号校验。

数据库 版本 并发 每请求 SQL P95 毫秒 堆池峰值之和 MiB
H2 改造前 1 122 15.918 109.12
H2 改造前 4 122 24.732 108.41
H2 改造后 1 8 8.023 109.50
H2 改造后 4 8 15.511 111.23
MySQL 改造前 1 122 2448.059 109.59
MySQL 改造前 4 122 2414.935 109.68
MySQL 改造后 1 8 173.823 110.11
MySQL 改造后 4 8 221.998 87.36

项目 SQL 从 122 降到 8,评论列表从 23 降到 4,20 用户后台列表从 22 降到 3。MySQL 四并发 P95 从 2414.935ms 降到 221.998ms,约降低 91%。本地微基准受运行波动影响,不能将 SQL 数变化等同于所有环境的固定延迟收益。堆池峰值是各 heap memory pool 的峰值之和,并非进程 RSS;普通小请求的内存收益不稳定,本期内存保护主要针对超大正文、无界上游响应和大文件并发。

复测:AI_ENABLED=false OSS_ENABLED=false mvn -pl vibemake-api -am -Dtest=QueryEfficiencyTest -Dsurefire.failIfNoSpecifiedTests=false '-DargLine=-Xms128m -Xmx512m' test。默认使用 H2;显式设置 BENCHMARK_MYSQL_URL、BENCHMARK_MYSQL_USERNAME、BENCHMARK_MYSQL_PASSWORD 时,自动创建并最终删除 vibemake_benchmark_* 随机临时库,执行 DDL 前验证连接 catalog 必须等于本次随机库。账号需要创建和删除临时库权限,禁止将基准改为直接重置业务库。该小样本不代表正式环境容量,部署仍需结合真实项目体量验证。