目录

CodeLoom · 织码

一个二进制,把代码托管与研发管理织在一起。

CodeLoom 是一套可完全自托管的研发协作平台。代码托管、合并请求、议题、需求 / 任务 / 缺陷、迭代看板、测试、流水线与文档跑在同一个进程里,共享同一份数据模型:提交、分支、合并请求与需求、缺陷、用例之间的关联是数据库里的一行记录,而不是两套系统之间的 Webhook 同步。

面向希望自建研发平台、对数据归属敏感、需要内网或离线部署的团队。

单二进制 · 内嵌前端 · SQLite 起步,可切 MySQL / PostgreSQL · Apache-2.0 · v0.0.1

目录

为什么是它

自建研发平台通常只有两条路:代码托管一套、项目管理另一套拼起来,或者采购一体化商业平台。前者要维护两套账号、两套权限、两套备份,跨系统的关联靠 Webhook 单向同步、经常断链;后者许可成本随人数上升,数据落在外部,私有化改造受限。

CodeLoom 的选择是自己实现一个整体:

  • 一个进程,不是一套集成。代码域与项目域同进程,通过领域事件与追溯关系表打通,没有同步延迟与丢事件,也不必为两套系统分别做运维、备份与升级。
  • 一套账号与权限。仓库级 RBAC 同时约束代码与工作项,不需要在两处各维护一份成员名单。
  • 零外部依赖也能跑。缓存、锁、限流、队列、事件总线、检索、对象存储、邮件等 11 项能力都有进程内实现,单机 SQLite + 本地磁盘 即可起步;需要扩容时再逐项切到 Redis / S3 / MinIO / Elasticsearch,改配置即生效。
  • 代价:全部自己实现与演进,因此先把「中小团队完整走完一遍研发流程」做扎实,再谈规模化(见项目状态)。

功能

代码托管

Smart HTTP 与 SSH 双协议推送,服务端钩子承接接收流程,浏览与 Diff 走 Go 原生实现。文件树、Diff、分支 / 标签、逐行归属(Blame)、原始文件、在线编辑(尊重分支保护)、仓库内文件名与内容搜索、提交统计与语言占比、归档下载、Release 与镜像同步。

协作评审

合并请求支持 merge / squash / rebase 三种合并方式与完整状态机;行级评论、评审人指派、分支保护规则、CODEOWNERS 归属要求,以及 pre-receive 钩子的直推拦截——绕过评审的推送在传输层就被拒绝。

议题

仓库内议题、标签、里程碑、星标、关注、派生。提交说明写 #12 建立关联,写 fixes #12 会在推送、网页提交、合并请求合并三条路径上自动关闭议题。议题不排期、不计工时,是「提交者 ↔ 维护者」的轻量通道,需要时再挂到工作项上。

研发项目管理

组织树 → 项目集 → 产品线 → 项目 → 需求 / 任务 / Bug 的完整层级;迭代与多套看板(含 WIP 限制)、燃尽图、工时登记、甘特图与依赖连线、资源负载、发布与构建记录、测试套件 / 用例 / 执行 / 失败建缺陷、文档库、需求跟踪矩阵与覆盖率、CSV 导出。工作项可关联提交、合并请求与分支。

流水线

YAML 定义流水线,Runner 轮询取任务,执行结果回写到合并请求的检查项上;构建产物与构建记录关联到提交和发布。

平台治理

用户 / 组织 / 团队与仓库级 RBAC、PAT、TOTP 双因素、审计日志、站内通知、全局与仓库内搜索、附件、大文件存储、提交时的密钥扫描(内置规则集与忽略名单)、依赖清单与漏洞扫描、Webhook 出站与入站。

逐条的路由与行为约定见模块能力清单,接口契约见 OpenAPI 定义。

快速开始

方式 前置条件
容器 Docker 24+ 与 compose 插件
源码 Go 1.26、Node 22、pnpm 9、系统 git

方式一:容器(生产样例,自带 PostgreSQL)

cd deploy/prod
cp .env.example .env      # 填 CODELOOM_SECRET_KEY(openssl rand -base64 32)、POSTGRES_PASSWORD、CODELOOM_EXTERNAL_URL
docker compose up -d --build

镜像需本地构建(compose 的 build 段已配好)。生产环境必须由反向代理终止 TLS,127.0.0.1:8080 只暴露给本机代理;environment=production 会对密钥强度、HTTPS 与 DSN 做启动校验,缺项直接拒绝启动。

方式二:从源码运行

make deps                 # go mod download + pnpm install
cp .env.example .env      # 设置 CODELOOM_SECRET_KEY
make dev                  # API :8080,前端 :5173(热更新)

启动时自动执行 migrations/;也可 make migrate-up 手动执行。默认 SQLite,要换 MySQL / PostgreSQL 改 .env 的 CODELOOM_DATABASE_DRIVER 与 CODELOOM_DATABASE_DSN,依赖可用 make dev-stack 起(compose 只提供数据库 / 邮件 / 对象存储)。

首次使用

  1. 打开 http://127.0.0.1:8080 → 注册。首个用户即管理员,自动创建个人组织
  2. 侧栏 仓库 新建或导入仓库;组织成员 管理协作权限
  3. 侧栏 Access Token 创建 cl_pat_...(只显示一次),或添加 SSH 密钥 走 2222 端口
git clone http://x:<cl_pat_xxx>@127.0.0.1:8080/{owner}/{repo}.git
git clone ssh://git@127.0.0.1:2222/{owner}/{repo}.git

配置

配置来自 configs/config.yaml,环境变量优先覆盖(完整模板见 .env.example)。

变量 默认 说明
CODELOOM_SECRET_KEY 无,必填 主密钥,加密凭证库中的 token / webhook secret;缺失时拒绝启动
CODELOOM_SECRET_KEY_FILE 空 从文件读主密钥,优先级高于上一行(K8s / docker secret)
CODELOOM_SERVER_ADDR 127.0.0.1:8080 HTTP 与页面监听地址
CODELOOM_SERVER_EXTERNAL_URL http://localhost:8080 对外地址,无尾斜杠;Webhook / LFS / Runner 链接依赖它
CODELOOM_SERVER_ENVIRONMENT development production 启用安全基线:强密钥 / HTTPS / DSN 校验
CODELOOM_DATABASE_DRIVER sqlite sqlite / mysql / postgres,同时决定迁移方式
CODELOOM_DATABASE_DSN ./data/codeloom.db 连接串;生产要求 TLS,SQLite 时连接数固定为 1
CODELOOM_DATA_DIR ./data 持久化目录:Git 仓库、LFS、附件、检索索引、备份
CODELOOM_LOG_LEVEL info debug / info / warn / error

密钥轮换的步骤写在同一份 .env.example 注释里:旧密钥写入 _OLD → 换新密钥并把 _VERSION 加一 → 重启后执行 codeloomctl admin rotate-secrets。

架构

六边形架构 + 领域驱动设计,四层单向依赖,装配只发生在一个地方:

cmd/            入口(服务进程 / 运维命令)
internal/
  domain/       实体、值对象、领域服务(零 IO)
  app/          用例编排:事务边界、事件发布
  adapter/      HTTP、SSH、Git 钩子、进程内端口实现
  infra/        持久化、事件总线、可观测性
  bootstrap/    唯一装配层:选实现、连依赖
web/            Vue 3 前端(构建产物 go:embed 进二进制)
migrations/     SQL 迁移,sqlite / mysql / postgres 三方言版本号对齐

四条依赖铁律由 make check-arch 强制:domain 不依赖上层、app 不依赖 adapter / infra、跨限界上下文不互相 import、适配器只保留一套实现。取舍理由见架构决策记录。

外部依赖可插拔:11 项基础能力统一走 platform/middleware 的驱动注册表,安装页与配置文件都能改,改动即时生效。

能力 默认(零依赖) 可切换为
缓存 / 锁 / 限流 / 队列 / 事件总线 进程内实现 Redis / Valkey / KeyDB
对象存储 本地文件系统 S3 / MinIO / OSS / COS
全文检索 Bleve Elasticsearch / OpenSearch
邮件 只记日志 SMTP

数据模型:82 张业务表按域加前缀(iam_ git_ pm_ qa_ doc_ ci_ ext_ sec_ sys_ cm_ ai_),看表名就知道属于哪一块。提交↔工作项、提交↔议题、合并请求↔工作项各有一张关系表:向上可以算需求与测试覆盖率,向下可以从一次提交列全它影响的需求、缺陷与用例。

技术栈

层 选型
后端 Go 1.26 · Chi · GORM
数据库 SQLite(默认)· MySQL 5.7+ · PostgreSQL 14+,同一套版本化迁移
前端 Vue 3 · TypeScript · Vite · Pinia · Ant Design Vue + Element Plus(经 @/components/base 封装)
交付 单二进制(内嵌前端)· 容器镜像 · Compose / Helm 样例

项目状态

v0.0.1 · 尚未对外发布。定位是单实例 + 内部用户 + 非关键数据的受控验证:代码托管 → 评审 → 议题 → 项目管理 → 测试 → 流水线这条主流程已能端到端走通,规模化与公网暴露所需的能力尚未完成。

明确的能力边界,避免误用:

  • 单实例部署。多副本需要外部中间件与无状态化改造,尚在规划
  • 面向内部可信网络。公网多租户的隔离、配额、防滥用尚未实现
  • 压测未在目标环境执行。10 万提交 / 500 并发克隆 / 1000 QPS 的脚本已就绪,结果待补
  • 不集成外部研发系统,也不做双向同步,数据只在本系统内(ADR-0004)

现状与优先级判定见功能覆盖与缺口,版本改动见 CHANGELOG.md。

开发与验证

命令 说明
make dev 后端 :8080(改 Go 自动重启)+ 前端 :5173(热更新)
make build 构建前端并嵌入二进制,产物在 bin/
make test Go 单元测试
make lint go vet + 前端 eslint(--max-warnings 0)
make check-arch 分层依赖门禁
make migrate-parity 三种方言的迁移版本号对齐校验
make e2e-smoke / e2e-git / e2e-pm 端到端验收(需后端已启动)
bash scripts/ui-e2e.sh 真实浏览器页面巡检(截图 + 报告)

提交前至少跑 make lint && make test && make check-arch。新增或修改代码时,注释按源码注释规范书写;改表结构需同时提交三种方言的迁移脚本,否则 parity 校验会失败。

文档

文档 内容
部署手册 构建、配置要点、容器形态与反向代理
备份与恢复手册 数据目录、备份策略、恢复演练
在线更新手册 codeloomctl update 的 patch / minor / major 分级与回滚
接口契约 HTTP API 的 OpenAPI 定义
架构决策记录 5 份 ADR
CONTRIBUTING.md 目录约定、命名规则、验证命令与变更流程
SECURITY.md 安全模型与漏洞报告方式
docs/README.md 工程文档与 UI 设计资产结构

贡献

欢迎提交 Issue 与 PR。开始前请先读 CONTRIBUTING.md:目录约定、命名规则、提交前必须通过的验证命令都在那里。安全问题请按 SECURITY.md 私下报告,不要开公开 Issue。

许可

Apache License 2.0。

关于
1.1 GB
邀请码
    Gitlink(确实开源)
  • 加入我们
  • 官网邮箱:gitlink@ccf.org.cn
  • QQ群
  • QQ群
  • 公众号
  • 公众号

版权所有:中国计算机学会技术支持:开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号