232 lines
29 KiB
Markdown
232 lines
29 KiB
Markdown
# 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 处理名额 |
|
||
| FILE_DOWNLOAD_MAX_BYTES | 1073741824,单文件流式下载上限 1 GiB,社区端和管理端均配置 |
|
||
| FILE_DOWNLOAD_TIMEOUT | 5m,获取 SHA、文件元数据、等待上游响应及读取响应体的总预算 |
|
||
| 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` 并记录安全诊断日志。部署时若覆盖该配置,需要与业务批量文件数对齐。
|
||
|
||
JSON 预览继续使用 50 MiB 文件读取上限,contents JSON 上限按单文件 Base64 膨胀量加 2 MiB 元信息计算,其他元数据 8 MiB,错误响应 64 KiB。GET 超限返回 502 GITEA_RESPONSE_TOO_LARGE;写入响应无法完整确认仍为 REMOTE_RESULT_UNKNOWN,持久化阻断后续仓库写入,不自动重试。
|
||
|
||
三个端的 `files?download=true` 改为同步流式转发:使用 Gitea 1.26.4 的 `contents-ext`(不传 `includes`)只查元数据,元数据响应上限 64 KiB,再按同一 SHA 请求 `/raw/`,以 64 KiB 缓冲区写出。单文件下载独立使用上述 1 GiB / 5m 配置;`FILE_MAX_CONCURRENT` 名额持有到传输完成、失败或取消。元数据、Content-Length 和实际读取字节数均校验,大小超限为 `413 FILE_TOO_LARGE`,超时为 `504 FILE_DOWNLOAD_TIMEOUT`。JSON 预览、编辑、上传和归档配额不变。
|
||
|
||
部署单文件下载路径时关闭代理响应缓冲和缓存,代理读取/发送超时默认至少预留 **400 秒**,并与调整后的下载预算保持一致;前端请求超时也至少预留 400 秒。应用下载预算约束上游处理和读取,慢客户端写出还受代理及容器超时约束。发包后故障直接停止传输,HTTP 可能仍为 200;前端应丢弃取消或截断的文件,不自动重试。上线后使用原 `doc/mujoco.gif` 下载链接验证文件长度与内容摘要。
|
||
|
||
### 依赖安全核对(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。
|