Files
community/README.md
T
2026-10-20 17:25:18 +08:00

33 KiB
Raw Blame History

Community

Spring Boot 社区后端,工程分层参考 cadworld。使用 Java 21、Spring Boot 3.5.7、MyBatis-Plus 3.5.11、MySQL 和 Gitea API v1。业务库名为 community,包含 sys_user、project、project_comment、project_like,以及管理端的 project_import_task。

平台管理用户、项目归属、类型、发布、评论、点赞和 Fork 来源;Gitea 管理文件、目录、Commit 与历史。仓库统一存放在配置的 Gitea 组织下,为私有仓库。

内置项目类型为 GENERAL(通用)、HUMANOID(人形)、QUADRUPED(四足)、WHEELED(轮式)、ROBOTIC_ARM(机械臂)。前端通过 /api/project-types 获取类型列表,用于项目创建、修改和列表筛选。

工程结构

模块 职责与主要包
community-api 应用入口、HTTP 接口和接口配置;使用 api.controller、api.config
community-bean 数据库实体在 bean.entity,常规请求与响应在 bean.Contracts,AI 协议在 bean.ai
community-service 业务 Service 接口在 service 根包,实现类在 service.impl;包含 mapper、config、gitea、ai、support
community-security 平台登录会话、验证码、身份上下文、认证过滤器和安全配置
community-common 通用响应、分页、异常处理、requestId 和基础工具
community-adminapi 独立管理端应用,用户角色鉴权、用户与全站项目管理、GitHub 在线迁移
community-import 固定 Excel 的 GitHub 项目运维导入命令,不提供 HTTP 接口

UserService、ProjectService、FileService、InteractionService、CoverUploadService、UrdfService 采用接口加实现类,Controller、安全模块和服务之间通过接口注入。GiteaClient 与 RestGiteaClient 定义仓库调用边界;项目锁、UTC 时间和分页检查归入 support。安全模块内的 TokenService、CaptchaService 保留具体类,首期沿用本机缓存。

功能与边界

支持邮箱加图片验证码登录、我的项目列表、在线文本编辑、新建文件和目录、上传及多文件提交、手动发布和撤回、已发布版本浏览、快照 Fork、平铺评论和点赞,以及可配置开启的 Maker AI(聊天问答、查找、创建空项目、Fork)。工作区是用户项目列表,没有 workspace 表。没有 repository_operation 表、草稿保存、类型表、标签、收藏、成员协作;管理后台接口由 community-adminapi 提供。

普通用户登录不验证邮箱归属,知道别人的邮箱也可能登录其账号;ADMIN 和 OFFICIAL 禁止通过该入口登录,后台管理员必须验证密码。 验证码和登录会话使用本机缓存,单实例部署,重启后重新登录。所有仓库写入统一经过平台后端。

启动

  1. 安装 Java 21、Maven 3.9+,准备 MySQL 8.0.13 及以上和现有 Gitea。
  2. 新建数据库手动执行 基础四表 SQL,并创建 迁移任务表。已有数据库执行管理端文档的增量 SQL;应用不会自动迁库。
  3. 在 Gitea 创建私有组织,将技术账号设为组织所有者,生成具有 write:repository、write:organization、read:user 权限的 Token。
  4. 将 .env.example 复制为 .env,填写数据库连接与 Gitea 地址、组织、Token;默认使用 test 环境,.env 被 Git 忽略,不提交真实凭据。
  5. 执行:
bash scripts/run-local.sh

当前机器已配置 Gitea 26.4.0,并建立私有组织 community。本机 .env 已保存 Gitea Token,权限为 0600;没有保存管理员密码。保留这些 Gitea 配置,再补充 DB_URL、DB_USERNAME、DB_PASSWORD 即可,不要用示例覆盖已有 Token。

直接部署时通过环境变量配置,运行打包后的 community-api/target/community-api-0.0.1-SNAPSHOT.jar。默认端口 8993,SERVER_PORT 或 PORT 可覆盖(SERVER_PORT 优先)。本机脚本会加载 .env,直接运行 jar 不会自动加载该文件。

接口文档:前端接口对接文档,包含全部接口、字段结构、请求响应示例、页面调用顺序和错误处理。启动后访问 /swagger-ui.html;机器可读 OpenAPI 为 /v3/api-docs。

环境与日志

配置与日志方式参考 cadworld:application.yml 保存公共配置,application-test.yml 和 application-prod.yml 分别保存环境相关的数据库、Gitea、跨域白名单和日志配置。不指定环境时默认 test,通过 SPRING_PROFILES_ACTIVE 或启动参数切换。

prod 启动时检查数据库连接、用户名、密码、Gitea 地址和 Token 是否已配置且非空;缺失时停止启动,错误信息只包含配置项名称。

配置 test prod
数据库 默认本机 community,可用 DB_* 覆盖 必须配置 DB_URL、DB_USERNAME、DB_PASSWORD
Gitea 默认本机地址,使用 GITEA_* 覆盖 必须配置 GITEA_BASE_URL、GITEA_TOKEN;组织默认 community
API 跨域来源 https://dev-vibemake.robotquan.com https://vibemake.robotquan.com
OSS 封面目录 vibemake_dev/project-covers/ vibemake/project-covers/
OSS URDF 目录 vibemake_dev/urdf/{projectCode}/{batchCode}/ vibemake/urdf/{projectCode}/{batchCode}/
连接池 最少 1、最多 10 个连接 最少 1、最多 20 个连接
项目日志级别 DEBUG INFO
日志目录 logs,可用 LOG_PATH 覆盖 logs,可用 LOG_PATH 覆盖

生产部署示例(先在部署环境配置以上连接变量):

SPRING_PROFILES_ACTIVE=prod java -Djava.awt.headless=true -jar community-api/target/community-api-0.0.1-SNAPSHOT.jar

本机脚本支持传递启动参数,例如 bash scripts/run-local.sh --spring.profiles.active=prod,此时加载 .env 中的连接信息并使用 prod 配置。测试和生产数据库、Gitea 组织需要各自隔离时,分别设置对应的 DB_、GITEA_ 变量。

跨域白名单由 community.cors.allowed-origins 指定,仅作用于 /api/**。支持 Bearer Token、JSON、文件上传下载和 AI SSE,预检缓存 3600 秒,暴露 X-Request-Id、Content-Disposition,不启用跨域 Cookie 凭据。启动日志会记录生效的白名单。默认不开放 HTTP、localhost、其他端口或跨环境来源;本地继续使用前端开发代理,配置见开发代理示例。部署代理需透传预检请求、Origin 和后端 CORS 响应头,避免重复添加跨域头;OSS Bucket 的 CORS 仍需独立配置。

日志配置沿用 cadworld-common 的 logback-spring.xml 模板,放在 community-common;应用名为 community-api。测试和生产默认都写入 logs,可用 LOG_PATH 覆盖目录;目录相对于应用启动时的工作目录。本机启动脚本从项目根目录运行。

同时输出控制台、community-api.log 和 community-api-error.log,日志时间使用 Asia/Shanghai,格式包含线程、级别、requestId 和类名。应用日志按天或每 100MB 归档,保留 30 天、总归档上限 10GB;错误日志仅接收 ERROR,按天或每 50MB 归档,保留 60 天、总归档上限 5GB。归档写入 archive 子目录并压缩为 gzip。SQL Mapper 和 Spring Web 保持 INFO,不记录凭据、邮箱或代码内容。

验证

mvn clean verify

普通测试固定使用 test 配置,覆盖连接为临时 H2 MySQL 模式及模拟 Gitea/AI/OSS,验证登录、权限、提交冲突、发布快照、Fork、评论、点赞、URDF 直传核验和独立复制,以及 AI 筛选、引用校验、创建、Fork 与候选选择、SSE、限流、超时和取消,不访问真实数据库、仓库、对象存储或模型。未加载外部服务凭据时,执行 AI_ENABLED=false OSS_ENABLED=false mvn test;AI 流程测试自行启用模拟模型。完整安装验证可执行 AI_ENABLED=false OSS_ENABLED=false mvn clean install。

真实 Gitea 联调:

python3 scripts/test-gitea.py

该测试使用临时 H2 数据库,在配置的组织创建临时项目仓库,验证私有仓库、多文件提交、中文路径、二进制上传、固定发布版本及快照 Fork,结束后仅删除本次测试创建的仓库。Gitea 26.4.0 内置的 1.26.4 支持批量文件变更;以服务器 /swagger.v1.json 为对接依据。

测试 Gitea 组织仓库复制到生产

scripts/migrate-gitea-org.py 使用 Python 3.9+ 标准库,将测试 community 下的 Git 仓库复制到生产 vibemake(组织可通过参数修改)。生产 Gitea 应先初始化,并创建目标组织。目标为同名私有普通仓库,保留默认分支、历史、分支和标签,并请求迁移 LFS;不复制 Issue、PR、Release、Wiki、用户、组织成员、权限、Webhook 或 Actions 执行记录,也不导入 Gitea 整库、不复制实例配置。

两端账号需是对应组织的所有者或站点管理员。测试 Token 需有 read:repository、read:organization、read:user、read:misc,生产 Token 需有 write:repository、write:organization、read:user、read:misc;仓库访问范围应包含私有仓库。迁移期间暂停源组织写入、导入任务以及目标后端写入,Gitea 本身保持运行。生产 Gitea 容器必须能通过 HTTP Git 和 LFS 访问测试地址,两端开启 HTTP Git/LFS,生产开启仓库迁移。

在项目根目录执行(替换地址):

# 两次提示分别输入测试、生产 Token,输入不回显,不会写入命令历史。
# 默认只读预览;不自动读取现有 .env,避免把两个环境的凭据混用。
python3 scripts/migrate-gitea-org.py \
  --source-url https://测试Gitea域名 \
  --target-url https://生产Gitea域名 \
  --dry-run

# 先复制一个尚未处理的仓库。
python3 scripts/migrate-gitea-org.py \
  --source-url https://测试Gitea域名 \
  --target-url https://生产Gitea域名 \
  --execute --limit 1

# 抽查通过后,用相同状态目录续跑其余仓库。
python3 scripts/migrate-gitea-org.py \
  --source-url https://测试Gitea域名 \
  --target-url https://生产Gitea域名 \
  --execute

可重复指定 --repo p_项目编码 限定仓库;--source-org 默认 community,--target-org 默认 vibemake。非交互执行可通过 GITEA_MIGRATION_SOURCE_TOKEN、GITEA_MIGRATION_TARGET_TOKEN 注入凭据,不接受 Token 命令行参数。默认只允许 HTTPS;仅在可信网络确需明文连接时指定 --allow-http。API 请求不跟随重定向,不将凭据放入 URL、状态文件或日志。迁移请求会将源账号和 Token 放在发往生产 Gitea 的请求体中,生产 Gitea 用它们读取源私有 Git/LFS。单仓库请求超时默认 1800 秒,可用 --migration-timeout 调整;生产反向代理的超时也应相应配置。

--state-dir 默认 logs/gitea-org-migration,同一批次只允许运行一个进程;目录权限 0700,文件权限 0600。目录绑定源/目标地址、组织和初始仓库清单;组织仓库发生增删或同名重建时停止,不自动改变迁移范围。state.json 保存进度、源分支/标签快照及成功迁移返回的目标仓库标识;mapping.json 仅包含已取得 HTTP 201 完成收据并核对仓库身份、私有属性、默认分支、分支和标签提交的记录。LFS 由 Gitea 迁移流程处理,脚本不逐对象下载核验;先试迁一个带 LFS 的仓库,用 git lfs pull/实际下载检查实体后再批量执行。子模块只保留 Git 引用,不递归复制其他仓库。

生产同名仓库标记 CONFLICT,不接管、不覆盖。超时、服务端错误、返回状态不明确或迁移中断时标记 REVIEW,停止本次新增仓库;Gitea 可能仍在后台执行,不能仅凭仓库存在认定 LFS 已完成。保留状态目录并核对生产日志及仓库;没有成功收据的记录不会自动重发。有成功收据、仅核验失败的记录,在续跑时只读核对。不要删除状态文件来盲目重试,也不要自动删除生产仓库。退出码 0 表示本次无冲突/待核对项(预览或 --limit 仍可能有 PLANNED),2 表示存在 CONFLICT/REVIEW,1 表示预检或运行环境错误。

历史导入中断后,源数据库的 empty 标记可能与磁盘内容不一致;脚本会检查实际 Git 引用,存在引用时按 Git 对象 SHA 核对分支和标签。LFS 还需核查迁移日志:Gitea 可能忽略源端缺失的 LFS 对象后仍返回 HTTP 201。出现 Ignoring missing upstream LFS object 时,应按对象 SHA-256、大小建立缺失清单,从可信原始上游或备份恢复,并验证生产端实体可下载;不能把成功响应当作缺失文件已补齐。

仓库复制后,生产社区后端设置自己的 GITEA_BASE_URL、GITEA_TOKEN 和 GITEA_ORGANIZATION=vibemake。此工具不连接业务数据库;已复制到生产的 project 记录还需按 mapping.json 核对项目编码及原仓库标识,再在生产业务库回写 gitea_owner 和新的 gitea_repo_id,保持 gitea_repo_name、发布提交 SHA 等值,并确认已发布 SHA 可读取。gitea_repo_id 有唯一索引,回写需处理旧标识与新标识的冲突;备份后在维护事务中执行,不改测试业务库。原 GitHub 导入批次的收据不能直接当作新生产仓库收据复用。OSS 封面、URDF、业务用户及项目记录的复制需单独处理。

项目封面与 OSS 直传

项目 API 的 coverUrl 接收和返回完整 HTTPS 地址,平台封面在数据库中保存 /project-covers/... 环境相对路径,外部图片保留完整 URL。无封面时返回 null;创建时可省略,修改时省略或 null 保留原值,传空字符串清除。Fork 继承同一资源引用,替换、清除或删除项目不自动删除 OSS 图片。URDF 同样保存 /urdf/... 环境相对路径,上传和 OSS 操作仍使用含环境根目录的真实 key。人工迁移和回退见 数据库说明。

已有数据库必须先执行 封面字段升级 SQL,再部署新应用;新建数据库使用更新后的建表 SQL。应用不会自动变更表结构。

OSS 默认关闭,外部 HTTPS 封面仍可使用。启用时设置 OSS_ENABLED=true,并配置 OSS_REGION、OSS_BUCKET、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET。地域 ID 使用 cn-beijing 等编码,不带 oss- 前缀。Endpoint 默认根据地域推导为 https://oss-{region}.aliyuncs.com,无需配置环境变量;特殊域名场景可显式配置 community.oss.endpoint,使用可供浏览器访问的公网 HTTPS 地址,不包含 Bucket、路径或查询参数。OSS_PUBLIC_BASE_URL 可选,用于公开 CDN/OSS 基础地址;省略时使用 Bucket 标准 HTTPS 域名。启用但配置缺失或不合法时停止启动,未启用时签名接口返回 503 OSS_UNAVAILABLE。

目录由环境配置指定:test 使用 vibemake_dev/,prod 使用 vibemake/;二者均为桶内对象前缀。凭据使用仅能写入对应环境 project-covers/* 路径的 RAM 用户,密钥保留在服务端。实际 Bucket 和 CDN/OSS 域名由部署环境提供,不由应用创建。

登录后请求 POST /api/uploads/project-covers/signature,获得 OSS POST V4 表单和固定 coverUrl。签名有效期 5 分钟,支持 JPG、PNG、WebP,单张最多 5 MiB。浏览器直传成功后再保存项目,后端不接收图片内容。签名支持创建项目前上传;当前不提供上传完成回调、服务端图片内容检测或未绑定图片自动清理。

Bucket 需要配置前端实际域名的 CORS,允许 POST;图片通过公开读取规则或公开 CDN 地址访问。完整配置步骤、错误处理和前端 FormData 示例见封面上传接口。官方协议参考 OSS POST V4 和服务端签名直传。

部署验收:在 test 环境登录,获取签名、浏览器直传、保存项目并匿名访问封面;确认 OSS 对象位于 vibemake_dev/project-covers/,网络请求中的图片内容直接发往 OSS。prod 切换到 vibemake/project-covers/,图片地址不带临时下载签名。

Maker AI

设置 AI_ENABLED=true 和 ARK_API_KEY 后启用,默认模型为 doubao-seed-2-1-lite-260915,地址为 https://ark.cn-beijing.volces.com/api/v3/responses。使用 ARK_MODEL、ARK_ENDPOINT 可覆盖。与 cadworld 一样使用 Responses API 和 JSON Schema,关闭深度思考,store=false;密钥只在后端读取。未开启时接口返回 503 AI_UNAVAILABLE;开启但没有密钥时停止启动。

登录后调用 POST /api/community/ai/chat,通过 SSE 获取阶段、结果或错误。对话由前端保留最近6轮,刷新后清空,不保存到数据库。

Maker AI 支持身份介绍、日常闲聊、一般知识和技术问答,包括文本代码示例。聊天与意图识别共用一次模型调用,返回 CHAT、完整 reply、空 projects 和 null project,不联网、不执行代码、不写入项目。回复最多2000字符,可直接加入 history;聊天只有 understanding → result 两个 SSE 事件,不逐字输出。前端收到 CHAT 后追加历史并保留 previousProjectCodes,支持搜索后穿插闲聊再选择项目。

同时支持查找、创建空项目和 Fork 已发布项目;模型提取结构化项目意图,后端校验后复用现有项目服务,每轮最多一次写入。闲聊不会触发历史中的待办或已完成操作。创建时可生成名称和目标描述,类型无法判断时默认 GENERAL,仅初始化仓库和默认 README。Fork 默认沿用来源名称,按执行时的当前发布版本复制;查找并 Fork 仅在本轮唯一推荐结果时执行,多个候选返回 NEEDS_SELECTION 供下一轮选择。成功通过 CREATED/FORKED 和 project 返回新项目,前端使用 projectCode 进入工作区。

查找时仅检索已发布且仓库就绪项目的名称、描述、类型:先理解需求,再查询最多20个候选,最后排序并校验最多5个项目卡片。项目编码、引用原文和当前发布状态由后端校验;缺少依据的明确要求不算匹配,未证实的偏好单独列出。

每次模型调用默认30秒,模型/搜索阶段65秒;进入 Fork 阶段后采用独立5分钟预算并保留15秒入口及终态余量,前端和代理读取超时至少400秒;AI_REQUEST_TIMEOUT、AI_SEARCH_TIMEOUT 可调整。AI_MAX_CONCURRENT 默认4,AI_REQUESTS_PER_MINUTE 默认每用户10次,均为单实例内存控制,超限不排队。连接断开时尽力取消上游调用,实际工作结束后释放并发名额。写入开始后取消或超时不保证回滚;错误事件保留初始化异常中的 projectCode,先核对工作区,不自动重发创建或 Fork。AI 错误不影响普通项目搜索。前端请求和 SSE 解析示例见接口文档的“Maker AI”。

本期不读取 README、代码或评论,不建立向量索引,不修改四表结构。检索效果依赖项目描述,建议写清用途、技术栈、主要硬件和适用场景。描述修改即时生效;工作区文件提交仍须重新发布才更新社区代码。

真实模型联调(会调用方舟并产生模型用量):

python3 scripts/test-ai.py

脚本在内存 H2 中建立公开示例项目,验证 Maker AI 身份介绍、代码问答、多轮聊天、闲聊不重放创建/Fork,以及四足检索后穿插闲聊再改为轮式,默认 Maven 测试跳过该联调。密钥从当前项目 .env 或环境变量读取,脚本不输出密钥、不写真实数据库、不访问 Gitea。

Git 快照 Fork

后端保留鉴权、项目编码、来源记录和 OSS 复制,仓库数据通过 Git 对象级传输。按发布 SHA 的根 tree 生成一个无父提交,只推送新 main;保留普通大文件、文件模式、符号链接和子模块引用,不继承上游历史、其他分支或标签。子模块依赖仓库不递归复制。LFS 仅传输发布快照所需实体,推送后从新副本独立下载校验;不会只有指针却缺少实际对象。

应用运行用户的 PATH 需要包含 Git 和 git-lfs(本机验证 Git 2.52 / git-lfs 3.8)。CI 同样安装这两个程序,执行本地 Git 仓库及模拟 LFS 协议测试;普通业务测试替换仓库传输边界,不访问外部服务。启动时检查依赖,缺失仅使 Fork 返回 FORK_UNAVAILABLE,不阻止普通创建或其他接口。

开发环境可通过 brew install git git-lfs 安装;Debian/Ubuntu 的 CI 或部署镜像安装 git、git-lfs 软件包。以应用运行用户执行 git --version 和 git lfs version 确认 PATH 生效,无需执行全局 git lfs install。LFS 传输通过任务内的本地端点校验转发,拒绝 HTTP 重定向及指向其他地址的 action URL;临时目录禁止写入 git-lfs 原始错误报告,防止环境凭据落盘。

配置 默认值 用途
FORK_GIT_EXECUTABLE git Git 可执行文件路径,git-lfs 从子进程 PATH 查找
FORK_TIMEOUT 5m Git、LFS、核验和 OSS 共用的总时间预算
FORK_MAX_CONCURRENT 2 单实例并发上限,实际工作结束后释放名额
FORK_MAX_TEMPORARY_BYTES 5368709120 每次临时磁盘上限,含 LFS 源缓存与副本校验缓存
FORK_TEMPORARY_DIRECTORY 系统临时目录/community-fork 建议使用容量充足的独立临时磁盘

服务账号的 GITEA_TOKEN 需同时允许 REST 仓库创建、HTTP Git 读写及 LFS 读写。凭据通过进程环境注入,只用于配置的 Gitea 地址;不写入 URL、命令参数、Git 配置或日志。Fork 接口继续同步返回,前端和反向代理读取超时至少400秒;AI 进入 forking 后切换专用预算并继续发送心跳。

Fork 不受普通在线文件读取的10 MiB限制,文件浏览、下载和 LFS 在线展开能力仍维持原规则。失败时先核对响应 data.projectCode:明确失败为 FAILED,远端写入或数据库状态待核对为 CREATING;不会自动重发、删除远端仓库或 OSS 对象。完成后清理本地临时目录。使用 scripts/test-gitea.py 可执行显式真实 Gitea 联调,仅创建并清理本次测试专用仓库,不修改已有社区项目。

运行约定

项目名称、描述、类型、封面修改直接更新展示;工作区代码提交后,社区仍读取已发布 SHA,需要手动更新。Fork 复制已发布文件快照,不继承上游提交历史,也不自动同步。项目删除采用逻辑删除,保留仓库和已有 Fork。

创建或 Fork 前先写入 CREATING 项目,成功后标记 READY。结果不明或数据库回写失败需要人工核对;不提供后台自动恢复、无条件自动重试或跨重启完整幂等。具体恢复方式见接口文档。

项目短编码与 GitHub 初始化导入

历史外链封面转存 OSS

scripts/migrate-project-covers.sh 读取本项目 .env,将数据库现有外链图片下载并转存至当前环境 OSS,上传并核验成功后才更新 cover_url。配置 DB_URL、DB_USERNAME、DB_PASSWORD、OSS_REGION、OSS_BUCKET、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET;带 & 的 JDBC 地址必须加引号。环境根目录沿用 test 的 vibemake_dev 或 prod 的 vibemake。

# 默认只读预览,不下载、不上传、不更新数据库。
bash scripts/migrate-project-covers.sh --dry-run
# 先迁移三个项目,核对新封面的访问效果。
bash scripts/migrate-project-covers.sh --execute --limit 3
# 迁移其余外链,默认并发 2。
bash scripts/migrate-project-covers.sh --execute

支持 JPG、PNG、GIF、WebP,按实际文件头识别类型,原图不压缩、不转码。默认单图最多 5 MiB,可用 --max-bytes 调整,上限 50 MiB;--concurrency 范围为 1~4。下载只允许公开 HTTPS 地址,每次跳转重新校验,不携带任何平台或 GitHub 凭据,不访问内网地址。失效、超时、超限及非图片资源保留原值并进入失败报告。

实际对象位于 {环境根目录}/project-covers/migrated/{图片SHA256}.{扩展名};数据库只保存 /project-covers/migrated/...。相同外链只下载一次,相同图片内容复用对象,已转存记录在再次运行时自动跳过;已属于本平台的完整 URL 也跳过,可按数据库迁移说明归一化。扫描包含已逻辑删除项目,以完成历史数据统一。未来新提交外链的行为不由此批处理修改。

每次运行在 logs/cover-migration/ 生成独立报告目录(可用 --report-dir 修改)。preview.json、report.json 只包含项目编码、来源主机、状态及错误码,不记录完整外链或查询参数。backup.jsonl 保存修改前原值和拟写入路径,更新前强制落盘;目录和备份文件分别仅允许当前用户访问。原值可能包含签名参数,应作为受限数据库备份保存,不上传仓库或发送聊天。回写通过项目编码和原始 URL 字节比较,跳过迁移期间被修改的封面,不改 updated_at,不覆盖其他字段。

失败时可以重跑;上传成功但回写未完成的对象也按内容哈希复用,不会自动删除可能共享的对象。退出码 0 表示成功或仅预览,1 表示配置、连接等整体错误,2 表示存在逐项失败。人工恢复时仅将仍等于 newCoverPath 的记录按项目编码还原为 originalCoverUrl,避免覆盖之后的编辑。

对已经核验过的失效链接,可使用 --source-overrides /绝对路径/备用源.json 指定备用下载地址,JSON 格式为 {"项目编码":"https://可信图片地址"}。下载走同一套 HTTPS、大小和图片类型校验;数据库条件比较及原值备份仍使用原来的外链。采用的备用源另存于受限权限的 source-overrides-backup.json,便于审计。已成功迁移的项目在重跑时照常跳过。网络中断最多重试三次,证书校验失败不会绕过验证。

项目编码与导入流程

普通创建、Fork 和导入的新项目使用 12 位小写项目编码,字符集为 0123456789abcdefghjkmnpqrstvwxyz。普通项目用安全随机数生成,项目编码唯一约束冲突最多重试 5 次;其他约束错误不重试。导入编码由 github-import:v1:<GitHub仓库ID> 的 SHA-256 前 60 位确定,避免重跑或仓库更名后重复创建。Gitea 仓库名称为 p_{projectCode}。历史 32 位编码、仓库及链接继续使用,数据库无需改表。

导入工具仅接受以下固定 Sheet:1_轮式机器人、2_四足机器人、3_小人形机器人、4_大人形机器人、5_机械臂、6_其他类型、7_开源硬件。只选 I 列精确为“可访问”、L 列有合法 HTTPS 封面、B 列为具体 GitHub 仓库的行。其他 Sheet 不参与导入;K 列图片公式不会执行。原始 A~H 数据列与表头存在错位,工具按实际位置读取,忽略 H 列的无意义备注 100,不将“待查”等信息改写成已确认。

外部封面保留原 URL 和 GIF,不转存 OSS;当前环境的平台封面统一转换为相对路径。描述由原中文简介和技术资料组合,不调用 AI。轮式、四足、人形分别映射对应类型,机械臂映射 ROBOTIC_ARM,其他和硬件映射 GENERAL,原始分类保留在描述里。

脚本加载本项目 .env,依赖 Java 21、Maven,以及正式执行时可用的 MySQL 和 Gitea。独立导入模块不启动 Web 服务,也不加载登录、AI 或 OSS 客户端;只读取资源地址配置,不需要 OSS 凭据。test/prod 根目录与在线应用一致,历史公开地址使用 OSS_LEGACY_PUBLIC_BASE_URLS。Gitea 技术账号需具备组织所有者及仓库写权限,实例需开启迁移、HTTP Git 和 LFS。GITHUB_TOKEN 可选,仅用于 GitHub 元数据 API;API 限流时读取同一公开仓库的 GitHub 网页,交叉核验仓库 ID、规范地址、公开状态和默认分支,缺失或不一致则预检失败。网页和图片请求均不携带凭据。GITEA_TOKEN 仅访问配置的 Gitea,不能代替 GITHUB_TOKEN;切勿把 Token 放进 URL 或命令参数。

IMPORT_EXCEL='/绝对路径/项目.xlsx'
# 仅验证静态筛选,不访问网络、业务库或 Gitea。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --offline
# 默认 dry-run:在线检查仓库和图片,并生成清单;不写业务库或 Gitea。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --dry-run
# 先试导前三个尚未完成的候选。必须使用已有有效用户的 userCode。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --execute --owner-user-code '<用户编码>' --limit 3
# 试导检查通过后,用相同状态目录续跑其余项目。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --execute --owner-user-code '<用户编码>'

--owner-email 可替代 --owner-user-code 查找已有账号,二者互斥,工具不会创建用户;状态中始终保存查到的用户编码。--state-dir 默认 logs/github-import,包含原子写入的 manifest.json 和 report.json;此目录必须保留并备份,不能在迁移进行中删除。清单绑定 Excel 指纹、归属用户和 Gitea 目标,不能复用于另一文件或环境。同一目录有进程锁,--concurrency 默认为 2,可选 1~4;同一批次只运行一个进程。--limit 限制尚未完成候选的处理数量;已完成项目、迁移结果未知或不具备收据核对条件的 REVIEW 项目不计入。

工具先创建 CREATING 项目记录,直接调用 Gitea /repos/migrate,不先创建空仓库。迁移使用私有普通仓库、开启 LFS,保留 Git 内容、历史、分支和标签;不迁移工单、PR、Wiki 或 Release 附件。迁移成功收据先落盘,再关联项目并自动发布。独立迁移请求默认超时 1800 秒,可用 --migration-timeout-seconds 调整,普通 Gitea 请求超时不变。原默认分支不是 main 时补建 main 并设为默认,保留原分支;同名 main 内容冲突时停止该项目,不覆盖源分支或已冻结版本。

进程在 MIGRATING 阶段中断,或迁移超时、结果不明确时,项目进入 REVIEW,禁止自动重发或仅凭仓库存在判定成功。需要核对 Gitea 迁移及 LFS 完成情况、来源和提交后由维护人员处理;不要直接把 REVIEW 改为 READY 或删除仓库再重跑。已确认的迁移收据会用于数据库回写或发布失败后的续跑,避免重复迁移。对于已持久化成功收据、仅在主分支适配时出现不明写入结果的项目,续跑先只读核对仓库身份、来源、私有属性、默认分支和两条分支的冻结 SHA;全部一致才继续关联和发布,否则保持 REVIEW,不重发分支写入。已完成项目不会因后续人工撤回、修改或删除而被批次重新发布。

报告逐项包含 Sheet、行号、短编码、阶段、错误码和兼容性提醒。退出码 0 表示本次选定工作完成,1 表示命令、配置或持久化等致命错误,2 表示存在预检未通过、失败或待核对项目。在线仓库或图片失效会减少实际导入量;报告中的候选数仍与静态筛选对账。

本次只完成仓库迁移、关联和发布。在线浏览和下载仍有单文件限制,LFS 实体、子模块及符号链接的在线浏览能力未扩展;Git 快照 Fork 已支持大文件、LFS 实体、符号链接及子模块引用,依赖仓库仍不递归复制。当前发布快照检测到的限制会写入报告。子模块只保留引用,不递归迁移独立仓库,也不下载网盘或其他外链资源。保留所有分支不代表社区提供分支切换界面。

管理端

独立端口默认 8994,共用现有 sys_user,通过 USER/ADMIN/OFFICIAL 角色鉴权,不新增管理员或会话表。后台管理员以邮箱和 BCrypt 密码登录;会话使用本机缓存,默认 8 小时,重启后重新登录。第一版社区端和后台各单实例,Token 不互通。

启用前先手工执行 管理端 SQL,停止并排空旧写入进程,更新社区端、后台和 Excel 导入工具,最后启用后台。全部仓库写入端使用相同数据库的项目命名锁;不可让仍使用本地锁的旧版应用并行写入。

bash scripts/run-admin-local.sh
# 将一个已有普通用户初始化为管理员,交互输入密码,不传明文密码参数。
bash scripts/run-admin-local.sh --bootstrap-admin-user-code='<已有用户编码>'
# 真实 MySQL 验证:创建并删除随机临时库,不改现有业务数据。
bash scripts/test-admin-mysql.sh

前端对接见 管理后台接口文档,服务初始化、配置与故障处理见 管理端部署说明。数据库 SQL 不会由启动脚本自动执行;真实仓库迁移和正式发布需在部署后由管理员通过接口触发,普通测试不会访问真实 GitHub、Gitea 或 OSS。