Files
community/docs/admin-deployment.md
T
admin 1ae21eef5b git clone功能
网站登录 → 创建项目 Git Token → clone → 本地修改、commit → push main → 网站工作区刷新后显示最新内容 → 网站手动发布到社区
2026-11-03 10:42:08 +08:00

226 lines
28 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.
# Vibemake 管理端部署与运维
管理端为独立 Spring Boot 应用 `vibemake-adminapi`,默认端口 8994,接口前缀 `/admin-api`。项目文件复用现有 Gitea 私有组织仓库,封面、URDF 及四类模型/行走资源复用 OSS;不需要新建 Gitea 账号或组织。前端对接见 [管理后台接口文档](admin-api.md)。
## 部署与初始化
1. 备份数据库、暂停写入、排空旧进程。已有数据库手工执行 [增量 SQL](admin-database.md),新数据库先执行 [基础四表 SQL](database.md),再创建迁移任务表和普通文件写入操作记录表。应用不自动执行 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
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。
```bash
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` | 空;完整前端来源用英文逗号分隔,不使用通配符 |
| `PROJECT_RESOURCE_SIGNATURE_VALIDITY` | 1h;整机、零件、拼装 JSON、行走资源直传签名有效期 |
| `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 对象不会自动清理,沿用现有资源生命周期。
整机 GLB、零件 GLB 文件夹、拼装 JSON 和行走资源在项目 READY 后通过项目资源接口上传。升级前先手工执行 [八字段增量 SQL](admin-database.md#已有数据库增加四类项目资源字段)。RAM 用户需拥有当前环境 `project-resources/*` 的 `oss:PutObject`、`oss:GetObject` 权限,配置公开读取/CDN 及真实前端 Origin 的 POST、GET、HEAD CORS。新资源签名和确认清单不设置应用正文配额,反向代理须允许实际清单大小;文件内容由浏览器直接上传 OSS。Fork 对这四类资源只继承数据库引用,不调用 OSS;旧对象保留,后续任何清理机制均需检查共享引用。
STEP 上线前还需手工执行 [STEP 三字段增量 SQL](admin-database.md#已有数据库增加-step-单文件字段),然后更新社区端、管理端及导入进程。无需新增批次表。管理端 `STEP_MAX_FILE_BYTES` 默认 `524288000`(500 MiB),前端大小限制和文案须一致;URDF 限制和 API multipart 配额不变。沿用当前环境 `project-resources/*` 的 OSS 读写权限和公开读取配置,浏览器 POST 需允许管理端实际 Origin,CDN 需透传 Content-Disposition 附件下载响应头。
测试环境验收:签名 → 真实 OSS 上传 → 确认绑定 → 普通链接下载,检查中文文件名、500 MiB 边界、替换及重复移除;确认 Git SHA、发布状态和 URDF 不变。回滚应用时保留 STEP 列和对象。无状态确认不提供旧批次防复活保证。
## 异常核对
- 超时、进程在 MIGRATING 阶段中断或远端结果不明确时进入 REVIEW。禁止自动重发,也不能仅凭仓库存在判定成功。
- Gitea 明确返回 GITEA_MIGRATION_REJECTED 时显示 FAILED,提供重试。原有同错误的 REVIEW 任务也可申请重试;后台持有项目共享锁,在 CLEANING 阶段核验任务标识、组织、名称、来源及已记录的仓库 ID,清理后确认不存在再迁移。没有残留仓库时直接继续,不删除项目记录或 OSS 资源。
- 清理操作写入前持久化 CLEANING 阶段及仓库身份;删除超时或数据库回写失败时保持阻断,下次重试先核验是否已删除再继续。仓库已替换、来源不符、缺少任务归属标识时不删除;旧任务的无标识残留仓库仍需人工核对。已就绪、发布过的项目及已有成功收据的迁移不会走删除重迁流程。
- 人工核对后已删除目标仓库的任务,可在原任务页刷新并重试,无需修改状态或清空仓库 ID。后台重新确认仓库不存在后才清除旧仓库关联和写入阻断,保留原项目与资源继续迁移;再次点击不能绕过仍存在仓库的身份校验。
- REMOTE_RESULT_UNKNOWN 需要按 requestId、项目编码、任务编码核对日志和 Gitea,不应删除目标仓库后直接重跑。
- MIGRATING 阶段缺少成功收据、项目仍未就绪且未发布/删除的 REVIEW 任务,可通过原 retry 接口排队进入 VERIFYING。后台核验任务标识、来源稳定身份、目标组织和名称、私有非镜像属性、非空状态、两次读取的仓库身份及来源分支提交;核验通过后在同一事务保存仓库关联标识、恢复收据和冻结 SHA,再继续原有分支适配与关联流程。不删除、不重新迁移、不自动发布;任何核验失败都保持 REVIEW,原项目资源保留。
- 完成判断针对当前 Gitea 1.26.4 原生 `service=git` 非镜像迁移:初建库的 `empty=true`,Git/LFS 导入成功后才持久化非空状态。参见 [Gitea 原生迁移实现](https://github.com/go-gitea/gitea/blob/v1.26.4/services/repository/migrate.go#L121-L163) 与 [迁移收尾实现](https://github.com/go-gitea/gitea/blob/v1.26.4/services/repository/migrate.go#L218-L265)。缺少 empty 布尔属性的响应直接拒绝核验,不能使用 JSON 缺省值推断完成;升级 Gitea 或改用其他迁移方式前须重新验证该约定。
- VERIFYING 由管理员点击触发,沿用现有任务消费者;没有自动扫描 REVIEW 的定时恢复任务。核验期间服务重启后仍进入 REVIEW,可再次点击核验。仓库未完成可稍后再核验,标识/来源/仓库身份不匹配时由维护人员先核对;禁止手工把 REVIEW 改成成功。
- 已持久化成功收据且停在 MIGRATED 的任务,retry 会只读验证仓库身份、来源等后续跑。
- 停在 NORMALIZING/BRANCH_READY 且有冻结目标 SHA 的任务,retry 会核对已适配分支和收据后续跑;验证不通过继续阻断。
- 无强制成功、直接清除未知写入状态、任务取消接口。不能直接把 REVIEW 改成成功。
- 迁移成功不自动发布,先在 test 验证单个仓库及人工发布,再开放生产入口。
- 停用后台先关闭任务消费、排空正在执行的任务,再停止应用。不要在后台或 Excel 导入仍写入时回退社区端到旧写入逻辑。
逻辑删除、撤回和下架不会物理删除 Gitea 仓库或 OSS 对象;已公开 OSS 链接沿用现有生命周期。
### 普通项目后台自动核对
上线顺序:手工执行 [操作表 SQL](admin-database.md#新建普通文件写入操作记录表本次上线前执行) → 排空旧写入进程 → 同时升级社区 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 继续使用原专门核验流程。本阶段暂不提供管理员在线恢复入口。
## 验证
```bash
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 响应头公告](https://spring.io/security/cve-2026-22732/)、[Spring SSE 公告](https://spring.io/security/cve-2026-22735/)、[Spring UrlHandlerFilter 公告](https://spring.io/security/cve-2026-47883/)、[Tomcat 公告](https://tomcat.apache.org/security-10.html)、[Boot 依赖版本](https://docs.spring.io/spring-boot/3.5/appendix/dependency-versions/coordinates.html)。普通用户邮箱冒名登录按本次范围保留,后续更换登录方式时单独处理。
生产两端必须配置同一个目标 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 必须等于本次随机库。账号需要创建和删除临时库权限,禁止将基准改为直接重置业务库。该小样本不代表正式环境容量,部署仍需结合真实项目体量验证。
## HTTPS Git 网关运维
仅社区 API 暴露 `/git/**`;管理端继续使用后台认证。按 [README 配置](../README.md#https-git-网关) 部署独立 Git 技术账号、HTTPS 地址与无缓冲代理。功能默认关闭;先人工执行 [Git Token 表](database.md#项目-git-凭据) 与 [operation_kind 等字段扩展](admin-database.md#https-git-写入记录扩展),再排空旧进程并升级两个 API,最后对测试项目验证后开放。不能让旧版后台核对器消费 GIT_PUSH 操作。
Git 技术账号须非 site admin、非组织所有者、非仓库管理员,PAT 只给 read:user、write:repository。首次 Token 签发会按项目给技术账号授予 write,不提升其已有 admin/owner 权限;权限不兼容必须先人工处理。已有 main 保护不覆盖,通配/多规则配置会保守拒绝开通;每次 push 复核。运维直接修改仓库引用或 main 保护前应停写,不能绕过网关并发控制。LFS action 以短期 Redis 状态承接,上游地址与认证头只保留服务端。Redis 丢失 action 后需重新请求 batch;原 Git 凭据存 MySQL,可撤销。
网页与本地写入使用同一 ProjectLocks 和 repo_write_status,跨进程由 MySQL 命名锁串行。操作记录必须在转发 receive-pack 前提交,operation_kind=GIT_PUSH 记录 base_commit_sha、target_commit_sha、actor_user_code、git_token_code,摘要不含 pack。HTTP200 不是成功证明;仅接受完整 report-status,成功后再次核对 main,并原子保存终态与 IDLE。推送作者来自本地提交,审计 actor_user_code 是网站发起者,两者可能不同。
后台核对按类型区分:WEB_COMMIT 继续查找原有尾注;GIT_PUSH 先校验项目/远端仓库身份、私有属性及 main,再仅在 main 精确等于 target_commit_sha 时确认成功。main 仍等于 base_commit_sha、为其他SHA、上游不可用或读取失败均保持 REVIEW,不能自动判失败。10分钟后状态为 NEEDS_REVIEW,每分钟继续只读核对,不重发 push。
人工恢复顺序:
1. 关闭 Git 入口、停止并排空社区/后台仓库写入和发布,暂停核对 worker,保留数据库和日志备份。
2. 根据 requestId、projectCode、operationCode、actor_user_code、git_token_code、旧新 SHA 关联网关与 Gitea 接收日志。先确认对应 receive-pack/钩子任务已经结束;单次旧 SHA 查询不能作为结束证明。
3. 核对仓库ID、owner/name、私有、非镜像、main 及对象可达性。精确目标SHA且验证完成可确认 SUCCEEDED;确认任务停止且 main 仍为旧 SHA、未发生引用变更时才可人工标记 FAILED。main 为其他 SHA 或身份变化继续待核对,不改历史、不重推。
4. 在维护事务中同步更新操作 status/result_commit_sha/last_error_code/updated_at 和项目 repo_write_status=IDLE;必须校验项目只有这一条待核对操作,不能解除其他操作的保护。留存审批/排查依据和恢复审计,不能只执行孤立的 IDLE 更新。
5. 重启恢复进程、恢复 worker,验证网页及本地正常写入后再开放 Git。不自动发布社区。
回滚先关闭 Git 功能并排空接收请求,核对处理中操作后再回退应用。旧版本不能消费未解决的 GIT_PUSH;未解决前保持维护停写。保留新增表/列/凭据/审计、仓库内容及 main 保护,不删对象或撤销保护。功能关闭后仍可在网站查询、撤销 Git Token。