自托管、Git 原生、带实时协作与内置 Agent 的研发协作平台。
Kustos 不是对 GitHub API 的封装:仓库是 bare repo,代码浏览、搜索、PR diff、协作保存全部直接读写 Git 对象;元数据落在 PostgreSQL,实时通信走 WebSocket,Agent 以只读工具检索代码、写工具需人工审批。整套系统用一个 FastAPI 应用 + 一组 Compose 服务交付。
| 领域 | 能力 |
|---|---|
| 仓库与代码 | 仓库 CRUD、归档、Fork/Star/Watch;文件树、blob、提交历史、diff、blame、提交图、符号;分支与分支保护;Web 端提交;Git Smart HTTP / SSH / LFS |
| 协作流程 | Pull Request(草稿、行内评论、Review、三种合并方式、保护规则与 admin bypass);Issue(标签、指派、批量操作);Release 与附件;Webhook(HMAC 签名、重试、投递历史);通知(站内 / 邮件 / WebSocket) |
| 实时与社交 | 仓库频道、私聊、在线状态、跨 worker 广播;Yjs CRDT 协作文档(Hocuspocus 网关);协作邀请与会话级权限覆盖 |
| 搜索与 AI | 代码全文检索(块级索引 + ILIKE 子串匹配,暂未建 pg_trgm GIN 索引)、符号定义/引用、embedding 混合排序;Agent 作业(工具循环、流式、审批)、触发器(push / CI 失败 / 定时) |
| 平台与运维 | JWT 轮换与吊销、OAuth、仓库权限矩阵;动态配置(库表 + 热生效 + 密文密钥);审计与 Activity;Prometheus 指标、Grafana SSO;Admin 控制台 API |
| 层 | 选型 |
|---|---|
| 应用 | Python 3.12、FastAPI、SQLAlchemy 2(async)、Alembic、pydantic |
| 数据 | PostgreSQL 16 + pgvector(唯一数据库)、Redis 7(缓存 / pub-sub / Agent 队列) |
| Git | pygit2(libgit2)、git-http-backend、OpenSSH + 自定义 wrapper、LFS |
| 接入 | OpenResty 网关(静态资源 / API / WS / Git / 协作反代)、Hocuspocus(Node 22) |
backend/ # FastAPI 应用,后端镜像的构建上下文
├── app/
│ ├── api/ # 路由装配 + v1 控制器 + WebSocket
│ ├── core/ # 配置、初始化、生命周期、权限、异常
│ ├── middleware/ # 并发、审计、观测、指标
│ ├── models/ # SQLAlchemy 模型 + 同步/异步引擎
│ ├── services/ # 业务逻辑(含 agent / indexing / realtime)
│ └── utils/ # Git、Redis、安全、响应、邮件、Webhook
├── alembic/ # 数据库迁移
├── scripts/ # 容器内脚本:初始化、迁移、审计(随镜像发布)
└── tests/ # pytest
frontend/
└── web/ # Web 前端(Vite + React + TS),网关镜像的构建输入
services/
└── collab/ # Hocuspocus / Yjs 协作网关
docker/ # 镜像构建资料与运行时配置(gateway / git-cgi / sshd / 监控)
deploy/ # 宿主机部署入口:install / mgt / kustos / dev-start / generate_env
docker-compose*.yml # 生产 / 开发 / 监控编排(与 docker/ 同级)
docs/
├── code-wiki/ # 架构与实现文档(见下方索引)
├── desktop-app-design.md # 桌面端(Wails v3)设计
└── prototype/ # 静态原型:web/ 与 desktop/
前置:Docker + Compose V2、Python 3.12(uv)、PostgreSQL 16 + pgvector。数据库与 Redis 默认由 Compose 提供,宿主机不必单独安装。
python3 deploy/generate_env.py # 生成 compose 需要的密钥类变量(幂等,可重复执行)
docker compose -p kustos up -d --build # 构建并启动整套服务启动后:
| 入口 | 地址 |
|---|---|
| 网关(推荐入口) | http://127.0.0.1:8000 |
| API 直连 | http://127.0.0.1:8001 |
| Git HTTP | http://127.0.0.1:9000 |
| Git SSH | ssh://git@127.0.0.1:2222/<owner>/<repo>.git |
初始管理员账号在仓库根的 .env(KUSTOS_ADMIN_USERNAME / KUSTOS_ADMIN_PASSWORD),首次登录后请立即修改密码。生产部署前请阅读 docs/code-wiki/11-infrastructure.md 的网关、Admin ACL(KUSTOS_ADMIN_ALLOWED_SOURCES,留空即拒绝全部来源)与备份升级说明。
docker compose -p kustos --profile init run --rm init # 迁移 + 管理员引导
docker compose -p kustos --profile test run --rm test # pytest(容器内)
docker compose -p kustos -f docker-compose.monitoring.yml up -d # Prometheus + Grafana(可选)Web 前端在 frontend/web:Vite + React + TypeScript,Tailwind v4 + shadcn/ui 风格组件,
接口类型由后端 OpenAPI 生成。它同时是网关镜像的构建输入——镜像内用 Node 22 + pnpm 11 构建
dist 再交给 OpenResty 托管,因此宿主机无需装 Node。
cd frontend/web
pnpm install # pnpm 11;allowBuilds 在 pnpm-workspace.yaml,缺了 esbuild 装不上
pnpm dev # 开发服务器(/api 代理到后端)
pnpm build # 产物在 dist/,网关镜像取的就是这个目录
pnpm api:generate # 后端契约变了就重新生成类型详见 frontend/web/README.md。
方式 A:Compose(推荐,环境一致)
docker compose -f docker-compose.dev.yml -p kustos-dev up -d --build源码挂载热重载;网关在 127.0.0.1:18088,API 直连 127.0.0.1:18002(都取冷门端口,避开本机常见的 8000 段服务)。改完代码跑测试:
docker compose -f docker-compose.dev.yml -p kustos-dev run --rm test
docker compose -f docker-compose.dev.yml -p kustos-dev run --rm test python -m pytest tests/test_pull_request_service_async.py -q方式 B:裸进程 + 外部依赖
cd backend
uv sync --extra dev
export DATABASE_URL='postgresql://user:pass@127.0.0.1:5432/kustos'
export KUSTOS_SECURITY_SECRET_KEY="$(openssl rand -hex 32)"
alembic upgrade head
uvicorn app.main:app --reload --port 8000Windows 上直接在
D:\盘跑 Compose 会因跨文件系统(9p)导致构建与测试明显变慢;把仓库放到 WSL 原生盘(如~/<repo>)或在容器内运行即可。这属于个人开发习惯,仓库不附带同步脚本。
测试要求:PostgreSQL 16 + vector 扩展,账号需有 CREATEDB(每个会话建临时库、结束删除)。
静态检查(在本机装好 dev 依赖的环境里执行):
black app tests && isort app tests && flake8 app
python scripts/security_audit.pyWeb 与桌面原型(docs/prototype)都是纯静态页面,无需构建:
cd docs/prototype && python -m http.server 8765
# Web: http://127.0.0.1:8765/web/index.html
# Desktop: http://127.0.0.1:8765/desktop/index.html| 分册 | 内容 |
|---|---|
01-project-overview |
产品定位、功能全景、技术栈 |
02-architecture |
分层架构、请求链路、进程模型 |
03-bootstrap-and-config |
启动流程、配置系统与优先级 |
04-api-layer |
路由装配、认证与权限矩阵、控制器清单 |
05-data-model |
数据表、关系、约束 |
06-service-layer |
服务边界与调用方向 |
07-git-and-repository |
Git 存储、Smart HTTP/SSH、LFS |
08-collaboration-realtime |
WebSocket、房间、协作文档 |
09-search-and-indexing |
切块、符号、embedding、增量索引 |
10-agent-subsystem |
Agent 运行时、工具、审批、触发器 |
11-infrastructure |
网关、Compose、监控、部署 |
12-development-and-operations |
本地开发、测试、排障 |
13-dependencies |
模块依赖与 import 规则 |
Web 原型在 docs/prototype/web,桌面原型在 docs/prototype/desktop;设计稿与交互说明见 docs/prototype/README.md,桌面端实现设计见 docs/desktop-app-design.md。
- 分层:
controller → service → model。控制器只做参数与依赖编排,不写 SQL;服务层不解析 HTTP。层间依赖白名单由backend/tests/test_layer_boundary.py用 AST 强制(含函数体内的延迟导入),并带一条只收不放的「延迟导入棘轮」。 - 权限唯一裁决点:
app/core/permissions.py(纯策略)。全局管理员(User.is_admin)与仓库角色(owner/admin/developer/readonly)是两套授权,互不推导。组装成 FastAPI 依赖的工厂在app/api/guards.py。 - 迁移:模型改动必须配 Alembic 版本(
alembic/versions/),tests/test_schema_drift.py会比对模型与实际 schema。 - 注释:模块与函数使用中文 docstring(用途 /
Args/Returns/Raises);行内注释解释“为什么”,不转述实现。错误码与标识符保持英文。