GeekAI 仓库开发协作指南:从模块结构到构建测试的完整工程规范

原创2026-10-14 22:20:271,721 阅读
文章标签:人工智能AI 应用大模型媒体生成后端前端桌面应用认证鉴权

GeekAI 仓库开发协作指南:从模块结构到构建测试的完整工程规范

本文以仓库根目录的 AGENTS.md 为核心骨架,系统梳理 GeekAI(geekai)项目的工程组织方式:四大代码模块如何分工、本地开发与多架构构建命令、前后端编码规范、测试与提交(Pull Request)流程,以及密钥与敏感配置的安全处置原则。读者可据此快速理解仓库全貌,并照着命令清单在本机跑通「克隆 → 开发 → 构建 → 提交」的完整链路。

一、仓库全景:四个工程模块与辅助目录

GeekAI 是一个 Go + Vue3 的全栈 AI 创作平台,代码仓库从顶层就按「端」拆分,职责边界清晰。以当前仓库快照为准,顶层目录如下:

目录 角色 说明
api/ 后端服务 Go + Gin 实现的 API 服务,含 core/、handler/、service/、store/ 四层,配置与构建脚本同置
web/ 前端应用 Vue3 + Vite 工程,src/ 为源码,public/ 为静态资源,构建产物输出到 dist/
desktop/ 桌面客户端 Electron 壳,入口为 desktop/index.js,可打包多平台安装包
config/ 全局配置 存放全局 YAML 配置(当前快照中 config/config.yaml 为空占位文件,实际运行配置以 TOML 为主)
database/ SQL 脚本 数据库初始化脚本,如 database/geekai_plus-v4.2.6.sql
docs/ 文档 需求与部署相关文档
docker/ 容器编排 docker/docker-compose.yaml 一键拉起全套服务

需要说明的是,AGENTS.md 中提到的 miniprogram/(小程序壳)与 build/(Dockerfile、安装脚本)目录在当前仓库快照中并未包含,实际协作时以现有目录为准。

1.1 后端 api/:Gin + uber-go/fx 依赖注入

后端采用分层架构,api/main.go 是唯一入口,它使用 uber-go/fx 完成依赖注入与生命周期管理(api/go.mod 中声明 go 1.24.0,并引入 gin、gorm、redis 等核心依赖):

  • core/:业务内核。app_server.go 负责构建 Gin Engine 并注册全局中间件;config.go 负责 TOML 配置的加载与持久化;types/ 定义全部配置与业务类型(见 api/core/types/config.go)。
  • handler/:控制器层。普通用户 API 与 admin/ 子目录下的管理后台 API 分离,每个 Handler 通过 RegisterRoutes() 注册到 /api/v1/... 路由组。
  • service/:业务与三方集成。涵盖 AI 绘画(mj、jimeng)、音乐(suno)、视频(video)、PPT 生成、短信(sms)、支付(payment)、对象存储(oss)、文本审查(moderation)等。
  • store/:数据访问层。model/ 为 GORM 实体,vo/ 为视图对象,mysql.go、redis.go、leveldb.go 分别封装 MySQL、Redis 与本地 LevelDB。

main.go 中可以看到大量 fx.Provide(...) 与 fx.Invoke(...),例如:

  • 通过 fx.Provide(core.NewServer) 创建 Gin 服务;
  • 通过 fx.Invoke(func(s *core.AppServer, ...) { h.RegisterRoutes() }) 批量注册各模块路由;
  • 各类 AI 任务服务(MJ、Suno、Video、Jimeng)在启动时即调用 Run()、SyncTaskProgress()、DownloadImages() 等协程任务。

1.2 前端 web/:Vue3 + Vite + Pinia

前端源码集中在 web/src/,采用 Vue 3 Composition API,桌面端 UI 基于 element-plus,移动端基于 Vant(见 web/README.md)。状态管理使用 Pinia(web/src/store/),路由使用 vue-router(web/src/router.js)。构建配置见 web/vite.config.js:开发服务器默认监听 8888 端口,并将 /api 与 /static/upload/ 反向代理到后端地址(默认 http://localhost:5678),@ 与 ~@ 均指向 src/ 目录,产物输出到 dist/。

1.3 桌面端 desktop/:Electron 壳工程

desktop/package.json 定义了两条核心命令:start(electron .)用于本地调试,package(electron-builder)用于打包。构建配置中,Linux 目标为 AppImage、macOS 目标为 dmg、Windows 目标为 NSIS,图标分别使用 desktop/icons/logo.png、desktop/icons/logo.icns、desktop/icons/logo.ico。入口 desktop/index.js 实现典型的「加载页 + 主窗口」流程:启动时先隐藏主窗口并加载 loading.html,主窗口 loadURL 目标站点,待 did-finish-load 事件触发后最大化显示主窗口并关闭加载窗口。

二、构建、测试与开发命令速查

AGENTS.md 给出的命令全部可以在仓库中得到印证,以下逐一展开。

2.1 一键启动:docker-compose

docker-compose up -d

docker/docker-compose.yaml 定义了 5 个服务:MySQL 8.0.33(含 mysql_native_password 认证、healthcheck)、Redis 6.0.6(带密码、healthcheck)、Apache Tika(文档解析,端口 9998)、geekai-api 后端(端口 5678,通过 depends_on 等待数据库与缓存就绪)与 geekai-web 前端(Nginx,端口 8080)。后端容器通过环境变量 CONFIG_FILE=config.toml 指定配置,并把宿主机 ./conf/config.toml 挂载进容器(模板见 docker/conf/config.toml)。注意:拉起前需提前准备好 MySQL、Redis 与各模型平台密钥,并先构建或拉取对应镜像。

2.2 后端:热调试与多架构交叉构建

cd api && go run main.go

go run main.go 从当前目录读取 config.toml(默认配置文件名)。如果文件不存在,api/core/config.go 的 LoadConfig 会自动生成一份默认配置。仓库还提供了 api/fresh.conf,可配合 fresh 工具实现文件变更后的自动重启,实现热调试。

多架构构建使用 api/Makefile:

cd api && make amd64     # CGO_ENABLED=0 GOOS=linux GOARCH=amd64
cd api && make arm64     # CGO_ENABLED=0 GOOS=linux GOARCH=arm64 GOARM=7

两个 target 均关闭 CGO 并以 -ldflags "-s -w" 瘦身,产物为 api/bin/geekai-linux(make 默认同时构建 amd64 与 arm64),方便打进不同架构的容器镜像。这也与 docker-compose 中 geekai-api:v4.3.1-amd64 这类按架构打标签的镜像命名方式对应。

2.3 前端:安装、开发与构建

cd web && pnpm install
cd web && pnpm dev --host    # 或直接 pnpm dev(脚本内已含 --host)
cd web && pnpm build
cd web && pnpm lint

以上命令与 web/package.json 的 scripts 一一对应:dev 为 vite --host,build 为 vite build(输出到 web/dist/),lint 为 eslint . --ext .vue,.js,.jsx,.cjs,.mjs。构建产物可被 api/static/ 或 desktop/ 引用,实现一套前端多端复用。

2.4 桌面端:调试与打包

cd desktop && npm install
cd desktop && npm run start     # electron . 调试
cd desktop && npm run package   # electron-builder 打包多平台安装包

打包产物目标与平台对应关系已在上文 1.3 节说明,package 命令会根据当前运行平台生成对应格式(如 Linux 下产出 AppImage)。

三、编码风格与命名规范

3.1 Go 后端

  • 所有 Go 代码必须经过 gofmt/goimports,统一 tab 缩进与驼峰命名;
  • HTTP 路由遵循 /api/v1/resources 模式,例如 api/handler/ppt_task_handler.go 中的 /api/v1/tasks 路由组;
  • 每个 handler 类型命名为 ResourceHandler 并实现 RegisterRoutes(),与路由资源一一对应,这一约定从 main.go 中大量 fx.Provide(handler.NewXxxHandler) 的写法可以得到印证。

3.2 Vue 前端

  • 组件文件使用 PascalCase(如 ChatPanel.vue),与 web/src/components/ 下的实际文件命名一致;
  • Pinia store 与工具文件采用 kebab-case(如 chat-session.ts),对应 web/src/store/ 下的 session.js、sidebar.js 等文件;
  • 样式统一经由 ESLint、Tailwind(web/tailwind.config.js)与 web/postcss.config.js 约束,.vue、.js 等后缀文件均在 lint 检查范围内。

四、测试指南

AGENTS.md 明确了质量底线:

cd api && go test ./... -race

这是后端的最低要求。新增 service/handler 时需补 _test.go 文件,并用 mock 隔离第三方 API(避免真实调用外部 AI 平台);涉及时序逻辑的场景可新增 Test*Integration 用例验证。当前快照中 api/ 下暂未发现已提交的 _test.go 单测文件,api/test/ 目录是一个独立的调试程序 api/test/test.go,用于验证 Sora 服务从生成文本中抽取视频下载地址的辅助逻辑,可视为验证型小工具而非正式测试套件——正式单测仍按规范从零补齐。

前端暂未启用单测框架,因此最低要求是 pnpm lint 通过,并在 PR 中附关键页面截图或录屏证明交互可用;桌面端若修改了构建脚本,需在 macOS/Linux/Windows 三平台中至少验证一个安装包可用。

五、提交与 Pull Request 规范

  • 提交信息使用中文动词开头、聚焦单一变更,允许加子系统前缀,例如 web: 优化聊天动画,仓库历史中即有「支持腾讯云短信服务」这类先例;
  • PR 描述必须包含:变更背景、实现概述、验证方式(命令、截图或日志)以及关联的 issue/任务号;
  • 涉及配置或部署脚本的变更,还需要额外说明回滚流程,并 @ 相关 reviewer。

这套规范的本质是「可回溯、可验证、可回滚」,配合上面的测试底线,保证多人在同一仓库上的协作质量。

六、安全与配置提示

AGENTS.md 对敏感信息的管理提出了三条硬性要求,仓库配置结构也从机制上予以支持:

  1. 禁止提交真实密钥。后端采用 TOML 配置,开发时复制 api/config.sample.toml 为私有 config.toml(生产环境则使用 docker/conf/config.toml 作为挂载模板),并用 git update-index --skip-worktree 将私有文件标记为本地忽略,避免误提交。配置文件中的 SecretKey 是 JWT 授权密钥,注释明确要求「生产环境请务必更换」。
  2. 凭证统一入 Vault 或 CI Secret。代码中仅引用占位常量。从 api/core/types/config.go 可见,SMTP、支付(支付宝/微信/EPay)、OSS、短信等敏感配置均有独立配置结构,并在 api/core/config.go 的 LoadSystemConfig 中从数据库按配置键(system、oss、payment、smtp、sms、captcha、wx_login 等)逐项加载,运行期敏感参数不写死在源码里。
  3. 文档同步记录。新增敏感字段时需在 docs/ 中同步记录字段含义与启用步骤,方便后续维护者照文档完成配置。

七、小结

AGENTS.md 本质上是 GeekAI 仓库的「协作契约」,而这份契约的每条约定都能在源码与配置文件中找到落点:api/Makefile 印证多架构构建、web/package.json 印证前端脚本、desktop/package.json 印证 Electron 打包目标、docker/docker-compose.yaml 印证一键编排、api/core/config.go 与 api/config.sample.toml 印证配置加载与密钥隔离。按本文的顺序走一遍「读结构 → 跑命令 → 守规范 → 提 PR」,即可无缝接入该项目的日常开发与贡献流程。

登录后查看全文
geekai