.
一个二进制,把代码托管与研发管理织在一起。
CodeLoom 是一套可完全自托管的研发协作平台。代码托管、合并请求、议题、需求 / 任务 / 缺陷、迭代看板、测试、流水线与文档跑在同一个进程里,共享同一份数据模型:提交、分支、合并请求与需求、缺陷、用例之间的关联是数据库里的一行记录,而不是两套系统之间的 Webhook 同步。
面向希望自建研发平台、对数据归属敏感、需要内网或离线部署的团队。
单二进制 · 内嵌前端 · SQLite 起步,可切 MySQL / PostgreSQL · Apache-2.0 · v0.0.1
单二进制
内嵌前端
SQLite 起步,可切 MySQL / PostgreSQL
Apache-2.0
v0.0.1
自建研发平台通常只有两条路:代码托管一套、项目管理另一套拼起来,或者采购一体化商业平台。前者要维护两套账号、两套权限、两套备份,跨系统的关联靠 Webhook 单向同步、经常断链;后者许可成本随人数上升,数据落在外部,私有化改造受限。
CodeLoom 的选择是自己实现一个整体:
SQLite + 本地磁盘
Smart HTTP 与 SSH 双协议推送,服务端钩子承接接收流程,浏览与 Diff 走 Go 原生实现。文件树、Diff、分支 / 标签、逐行归属(Blame)、原始文件、在线编辑(尊重分支保护)、仓库内文件名与内容搜索、提交统计与语言占比、归档下载、Release 与镜像同步。
合并请求支持 merge / squash / rebase 三种合并方式与完整状态机;行级评论、评审人指派、分支保护规则、CODEOWNERS 归属要求,以及 pre-receive 钩子的直推拦截——绕过评审的推送在传输层就被拒绝。
CODEOWNERS
仓库内议题、标签、里程碑、星标、关注、派生。提交说明写 #12 建立关联,写 fixes #12 会在推送、网页提交、合并请求合并三条路径上自动关闭议题。议题不排期、不计工时,是「提交者 ↔ 维护者」的轻量通道,需要时再挂到工作项上。
#12
fixes #12
组织树 → 项目集 → 产品线 → 项目 → 需求 / 任务 / Bug 的完整层级;迭代与多套看板(含 WIP 限制)、燃尽图、工时登记、甘特图与依赖连线、资源负载、发布与构建记录、测试套件 / 用例 / 执行 / 失败建缺陷、文档库、需求跟踪矩阵与覆盖率、CSV 导出。工作项可关联提交、合并请求与分支。
YAML 定义流水线,Runner 轮询取任务,执行结果回写到合并请求的检查项上;构建产物与构建记录关联到提交和发布。
用户 / 组织 / 团队与仓库级 RBAC、PAT、TOTP 双因素、审计日志、站内通知、全局与仓库内搜索、附件、大文件存储、提交时的密钥扫描(内置规则集与忽略名单)、依赖清单与漏洞扫描、Webhook 出站与入站。
逐条的路由与行为约定见模块能力清单,接口契约见 OpenAPI 定义。
git
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 做启动校验,缺项直接拒绝启动。
build
127.0.0.1:8080
environment=production
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 只提供数据库 / 邮件 / 对象存储)。
migrations/
make migrate-up
.env
CODELOOM_DATABASE_DRIVER
CODELOOM_DATABASE_DSN
make dev-stack
cl_pat_...
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)。
configs/config.yaml
.env.example
CODELOOM_SECRET_KEY
CODELOOM_SECRET_KEY_FILE
CODELOOM_SERVER_ADDR
CODELOOM_SERVER_EXTERNAL_URL
http://localhost:8080
CODELOOM_SERVER_ENVIRONMENT
development
production
sqlite
mysql
postgres
./data/codeloom.db
CODELOOM_DATA_DIR
./data
CODELOOM_LOG_LEVEL
info
debug
warn
error
密钥轮换的步骤写在同一份 .env.example 注释里:旧密钥写入 _OLD → 换新密钥并把 _VERSION 加一 → 重启后执行 codeloomctl admin rotate-secrets。
_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、适配器只保留一套实现。取舍理由见架构决策记录。
make check-arch
domain
app
adapter
infra
外部依赖可插拔:11 项基础能力统一走 platform/middleware 的驱动注册表,安装页与配置文件都能改,改动即时生效。
platform/middleware
数据模型:82 张业务表按域加前缀(iam_ git_ pm_ qa_ doc_ ci_ ext_ sec_ sys_ cm_ ai_),看表名就知道属于哪一块。提交↔工作项、提交↔议题、合并请求↔工作项各有一张关系表:向上可以算需求与测试覆盖率,向下可以从一次提交列全它影响的需求、缺陷与用例。
iam_
git_
pm_
qa_
doc_
ci_
ext_
sec_
sys_
cm_
ai_
@/components/base
v0.0.1 · 尚未对外发布。定位是单实例 + 内部用户 + 非关键数据的受控验证:代码托管 → 评审 → 议题 → 项目管理 → 测试 → 流水线这条主流程已能端到端走通,规模化与公网暴露所需的能力尚未完成。
明确的能力边界,避免误用:
现状与优先级判定见功能覆盖与缺口,版本改动见 CHANGELOG.md。
make dev
make build
bin/
make test
make lint
go vet
--max-warnings 0
make migrate-parity
make e2e-smoke
e2e-git
e2e-pm
bash scripts/ui-e2e.sh
提交前至少跑 make lint && make test && make check-arch。新增或修改代码时,注释按源码注释规范书写;改表结构需同时提交三种方言的迁移脚本,否则 parity 校验会失败。
make lint && make test && make check-arch
codeloomctl update
欢迎提交 Issue 与 PR。开始前请先读 CONTRIBUTING.md:目录约定、命名规则、提交前必须通过的验证命令都在那里。安全问题请按 SECURITY.md 私下报告,不要开公开 Issue。
Apache License 2.0。
版权所有:中国计算机学会技术支持:开源发展技术委员会 京ICP备13000930号-9 京公网安备 11010802047560号
CodeLoom · 织码
一个二进制,把代码托管与研发管理织在一起。
CodeLoom 是一套可完全自托管的研发协作平台。代码托管、合并请求、议题、需求 / 任务 / 缺陷、迭代看板、测试、流水线与文档跑在同一个进程里,共享同一份数据模型:提交、分支、合并请求与需求、缺陷、用例之间的关联是数据库里的一行记录,而不是两套系统之间的 Webhook 同步。
面向希望自建研发平台、对数据归属敏感、需要内网或离线部署的团队。
单二进制·内嵌前端·SQLite 起步,可切 MySQL / PostgreSQL·Apache-2.0·v0.0.1目录
为什么是它
自建研发平台通常只有两条路:代码托管一套、项目管理另一套拼起来,或者采购一体化商业平台。前者要维护两套账号、两套权限、两套备份,跨系统的关联靠 Webhook 单向同步、经常断链;后者许可成本随人数上升,数据落在外部,私有化改造受限。
CodeLoom 的选择是自己实现一个整体:
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 定义。
快速开始
git方式一:容器(生产样例,自带 PostgreSQL)
镜像需本地构建(compose 的
build段已配好)。生产环境必须由反向代理终止 TLS,127.0.0.1:8080只暴露给本机代理;environment=production会对密钥强度、HTTPS 与 DSN 做启动校验,缺项直接拒绝启动。方式二:从源码运行
启动时自动执行
migrations/;也可make migrate-up手动执行。默认 SQLite,要换 MySQL / PostgreSQL 改.env的CODELOOM_DATABASE_DRIVER与CODELOOM_DATABASE_DSN,依赖可用make dev-stack起(compose 只提供数据库 / 邮件 / 对象存储)。首次使用
cl_pat_...(只显示一次),或添加 SSH 密钥 走 2222 端口配置
配置来自
configs/config.yaml,环境变量优先覆盖(完整模板见.env.example)。CODELOOM_SECRET_KEYCODELOOM_SECRET_KEY_FILECODELOOM_SERVER_ADDR127.0.0.1:8080CODELOOM_SERVER_EXTERNAL_URLhttp://localhost:8080CODELOOM_SERVER_ENVIRONMENTdevelopmentproduction启用安全基线:强密钥 / HTTPS / DSN 校验CODELOOM_DATABASE_DRIVERsqlitesqlite/mysql/postgres,同时决定迁移方式CODELOOM_DATABASE_DSN./data/codeloom.dbCODELOOM_DATA_DIR./dataCODELOOM_LOG_LEVELinfodebug/info/warn/error密钥轮换的步骤写在同一份
.env.example注释里:旧密钥写入_OLD→ 换新密钥并把_VERSION加一 → 重启后执行codeloomctl admin rotate-secrets。架构
六边形架构 + 领域驱动设计,四层单向依赖,装配只发生在一个地方:
四条依赖铁律由
make check-arch强制:domain不依赖上层、app不依赖adapter/infra、跨限界上下文不互相 import、适配器只保留一套实现。取舍理由见架构决策记录。外部依赖可插拔:11 项基础能力统一走
platform/middleware的驱动注册表,安装页与配置文件都能改,改动即时生效。数据模型:82 张业务表按域加前缀(
iam_git_pm_qa_doc_ci_ext_sec_sys_cm_ai_),看表名就知道属于哪一块。提交↔工作项、提交↔议题、合并请求↔工作项各有一张关系表:向上可以算需求与测试覆盖率,向下可以从一次提交列全它影响的需求、缺陷与用例。技术栈
@/components/base封装)项目状态
v0.0.1 · 尚未对外发布。定位是单实例 + 内部用户 + 非关键数据的受控验证:代码托管 → 评审 → 议题 → 项目管理 → 测试 → 流水线这条主流程已能端到端走通,规模化与公网暴露所需的能力尚未完成。
明确的能力边界,避免误用:
现状与优先级判定见功能覆盖与缺口,版本改动见 CHANGELOG.md。
开发与验证
make devmake buildbin/make testmake lintgo vet+ 前端 eslint(--max-warnings 0)make check-archmake migrate-paritymake e2e-smoke/e2e-git/e2e-pmbash scripts/ui-e2e.sh提交前至少跑
make lint && make test && make check-arch。新增或修改代码时,注释按源码注释规范书写;改表结构需同时提交三种方言的迁移脚本,否则 parity 校验会失败。文档
codeloomctl update的 patch / minor / major 分级与回滚贡献
欢迎提交 Issue 与 PR。开始前请先读 CONTRIBUTING.md:目录约定、命名规则、提交前必须通过的验证命令都在那里。安全问题请按 SECURITY.md 私下报告,不要开公开 Issue。
许可
Apache License 2.0。