2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +08:00
2026-10-14 10:26:20 +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 获取类型列表,用于项目创建、修改和列表筛选。

功能与边界

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

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

启动

  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
连接池 最少 1、最多 10 个连接 最少 1、最多 20 个连接
项目日志级别 DEBUG INFO
日志目录 logs/test logs/prod

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

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_ 变量。

公共模块的 logback-spring.xml 同时输出控制台、community.log 和 community-error.log,日志时间使用 Asia/Shanghai,包含线程、requestId 和业务编码。应用日志按天或每 100MB 归档,保留 30 天、总归档上限 10GB;错误日志按天或每 50MB 归档,保留 60 天、总归档上限 5GB。可用 LOG_PATH 覆盖日志目录。SQL Mapper 和 Spring Web 保持 INFO,不记录凭据、邮箱或代码内容。

验证

mvn clean verify

普通测试固定使用 test 配置,覆盖连接为临时 H2 MySQL 模式及模拟 Gitea,验证登录、权限、提交冲突、发布快照、Fork、评论、点赞和超时处理,不访问真实数据库或仓库。

真实 Gitea 联调:

python3 scripts/test-gitea.py

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

运行约定

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

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

S
Description
No description provided
Readme 36 MiB