17 KiB
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 四张表。
平台管理用户、项目归属、类型、发布、评论、点赞和 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-import | 固定 Excel 的 GitHub 项目运维导入命令,不提供 HTTP 接口 |
UserService、ProjectService、FileService、InteractionService、CoverUploadService 采用接口加实现类,Controller、安全模块和服务之间通过接口注入。GiteaClient 与 RestGiteaClient 定义仓库调用边界;项目锁、UTC 时间和分页检查归入 support。安全模块内的 TokenService、CaptchaService 保留具体类,首期沿用本机缓存。
功能与边界
支持邮箱加图片验证码登录、我的项目列表、在线文本编辑、新建文件和目录、上传及多文件提交、手动发布和撤回、已发布版本浏览、快照 Fork、平铺评论和点赞,以及可配置开启的 AI 对话搜索。工作区是用户项目列表,没有 workspace 表。没有 repository_operation 表、草稿保存、类型表、标签、收藏、成员协作或管理后台。
当前登录不验证邮箱归属,知道别人的邮箱也可能登录其账号。 验证码和登录会话使用本机缓存,单实例部署,重启后重新登录。所有仓库写入统一经过平台后端。
启动
- 安装 Java 21、Maven 3.9+,准备 MySQL 8 和现有 Gitea。
- 手动执行 四表建表 SQL,应用不会自动建表或修改数据库。
- 在 Gitea 创建私有组织,将技术账号设为组织所有者,生成具有 write:repository、write:organization、read:user 权限的 Token。
- 将 .env.example 复制为 .env,填写数据库连接与 Gitea 地址、组织、Token;默认使用 test 环境,.env 被 Git 忽略,不提交真实凭据。
- 执行:
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 |
| OSS 封面目录 | vibemake_dev/project-covers/ | vibemake/project-covers/ |
| 连接池 | 最少 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_ 变量。
日志配置沿用 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,验证登录、权限、提交冲突、发布快照、Fork、评论、点赞,以及 AI 筛选、引用校验、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 为对接依据。
项目封面与 OSS 直传
项目通过 coverUrl 保存固定公开图片地址,支持 OSS/CDN 或外部 HTTPS 图片。无封面时返回 null;创建时可省略,修改时省略或 null 保留原值,传空字符串清除。Fork 继承同一地址,替换、清除或删除项目不自动删除 OSS 图片。
已有数据库必须先执行 封面字段升级 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/,图片地址不带临时下载签名。
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轮,刷新后清空,不保存到数据库。仅检索已发布且仓库就绪项目的名称、描述、类型:先理解需求,再查询最多20个候选,最后排序并校验最多5个项目卡片。项目编码、引用原文和当前发布状态由后端校验;缺少依据的明确要求不算匹配,未证实的偏好单独列出。
每次模型调用默认30秒,整个搜索65秒;AI_REQUEST_TIMEOUT、AI_SEARCH_TIMEOUT 可调整。AI_MAX_CONCURRENT 默认4,AI_REQUESTS_PER_MINUTE 默认每用户10次,均为单实例内存控制,超限不排队。连接断开时尽力取消上游调用,实际工作结束后释放并发名额。AI 错误不影响普通项目搜索。前端请求和 SSE 解析示例见接口文档的“AI 对话搜索”。
本期不读取 README、代码或评论,不建立向量索引,不修改四表结构。检索效果依赖项目描述,建议写清用途、技术栈、主要硬件和适用场景。描述修改即时生效;工作区文件提交仍须重新发布才更新社区代码。
真实模型联调(会调用方舟并产生模型用量):
python3 scripts/test-ai.py
脚本在内存 H2 中建立公开示例项目,验证四足检索及多轮改为轮式,默认 Maven 测试跳过该联调。密钥从当前项目 .env 或环境变量读取,脚本不输出密钥、不写真实数据库、不访问 Gitea。
运行约定
项目名称、描述、类型、封面修改直接更新展示;工作区代码提交后,社区仍读取已发布 SHA,需要手动更新。Fork 复制已发布文件快照,不继承上游提交历史,也不自动同步。项目删除采用逻辑删除,保留仓库和已有 Fork。
创建或 Fork 前先写入 CREATING 项目,成功后标记 READY。结果不明或数据库回写失败需要人工核对;不提供后台自动恢复、无条件自动重试或跨重启完整幂等。具体恢复方式见接口文档。
项目短编码与 GitHub 初始化导入
普通创建、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 组件。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 实体读取、子模块及符号链接的浏览/Fork 能力没有扩展;当前发布快照检测到的限制会写入报告。子模块只保留引用,不递归迁移独立仓库,也不下载网盘或其他外链资源。保留所有分支不代表社区提供分支切换界面。