2026-10-15 11:09:21 +08:00
2026-10-15 11:09:21 +08:00
2026-10-14 16:55:07 +08:00
2026-10-14 16:55:07 +08:00
2026-10-15 11:09:21 +08:00
2026-10-14 16:55:07 +08:00
2026-10-15 11:09:21 +08:00
2026-10-14 10:26:20 +08:00
2026-10-15 11:09:21 +08:00
2026-10-14 10:26:20 +08:00
2026-10-15 11:09:21 +08:00

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(轮式)。前端通过 /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 和基础工具

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

功能与边界

支持邮箱加图片验证码登录、我的项目列表、在线文本编辑、新建文件和目录、上传及多文件提交、手动发布和撤回、已发布版本浏览、快照 Fork、平铺评论和点赞,以及可配置开启的 AI 对话搜索。工作区是用户项目列表,没有 workspace 表。没有 repository_operation 表、草稿保存、类型表、标签、收藏、成员协作或管理后台。

当前登录不验证邮箱归属,知道别人的邮箱也可能登录其账号。 验证码和登录会话使用本机缓存,单实例部署,重启后重新登录。所有仓库写入统一经过平台后端。

启动

  1. 安装 Java 21、Maven 3.9+,准备 MySQL 8 和现有 Gitea。
  2. 手动执行 四表建表 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
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、限流、超时和取消,不访问真实数据库、仓库或模型。完整安装验证可执行 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。结果不明或数据库回写失败需要人工核对;不提供后台自动恢复、无条件自动重试或跨重启完整幂等。具体恢复方式见接口文档。

S
Description
No description provided
Readme 36 MiB