gerardrecinto/devopsledger

# DevOpsLedger      **为 GitOps 团队提供的开源运营记忆库。**  当有人询问“为什么会发生这项基础设施变更？”时，DevOpsLedger 为平台团队提供了一个明确的答案。它将意图、diff、风险、审批、回滚准备情况、部署证据、事件后续及经验教训整合为一份持久的记录。 该 demo 包专为深度评估而构建：运行 API、打开 Web 门户、查看文档，并体验自托管路径，而无需注册 SaaS 账户或启用遥测。 ## 问题背景 平台工程团队每年会进行数百项基础设施变更。这些变更中的大多数都不会留下可用的记录。六个月后，没人能回答： - 为什么会发生这项变更？ - 是谁批准的？ - 哪些资源发生了变化？ - 风险有多大？ - 回滚是否真正就绪？ - 三周前发生的故障是这项变更导致的吗？ - 团队从中学到了什么？ 事件的回顾只能从 Slack、PR 描述和记忆中拼凑背景信息。而这些背景信息几天后就会遗失。 ## 解决方案 DevOpsLedger 将每一项基础设施变更转化为一份**决策记录**：包含意图、Terraform/OpenTofu diff、风险评估、审批、回滚准备情况、部署事件、事件关联以及经验教训。 它不是 CI/CD 仪表板，也不是工单系统。它是让基础设施变更在变更前、变更中和变更后都变得清晰可读的运营记忆层。 ## 社区版 DevOpsLedger CE 是开源、可自托管且免费的。它的设计初衷是在不升级的情况下就能提供真正的实用性。 **CE 功能（核心集成免费）：** - [x] 基础设施决策记录（意图、风险、审批、回滚、部署、经验教训） - [x] GitHub PR 获取（开源版 + GitHub Enterprise 基础版） - [x] Terraform / OpenTofu plan 解析 - [x] Argo CD 基础部署与 sync 事件 - [x] PagerDuty 故障与变更 webhook - [x] 通用事件 webhook - [x] Jira issue 链接解析 - [x] CODEOWNERS 审批检查 - [x] 风险评分（基于规则，可通过 YAML 配置） - [x] 回滚就绪度评分 - [x] 基础事件关联 - [x] 变更资源时间线 - [x] 基础仪表板 - [x] Docker Compose 部署 - [x] Helm chart - [x] 本地 / 离线模式 - 无需外部 SaaS 调用 - [x] 默认无遥测 ## 高级版（未来规划） 高级版将侧重于托管的便捷性、治理、合规性、企业身份、高级分析、AI 辅助和支持——而不是对核心 DevOps 功能进行限制。核心集成将保持免费。 计划推出的高级版功能：DevOpsLedger Cloud、团队工作区、SSO/SAML/OIDC、SCIM、RBAC、SOC 2 证据导出、高级分析、团队成熟度仪表板、AI 生成的变更叙述与事后复盘草案、企业集成、气隙企业套装、企业支持。 **支付和订阅功能尚未实现。** 请参阅 [docs/product-strategy.md](docs/product-strategy.md)。 有关商业化路径、市场切入角度及首批客户画像，请参阅 [docs/go-to-market.md](docs/go-to-market.md)。 ## 自托管。无需 SaaS。无遥测。 DevOpsLedger 优先支持本地部署。它完全可以在不进行外部 SaaS 调用的情况下运行。所有集成为可选且默认禁用。在完成初始镜像拉取后，可在气隙环境中运行。 请参阅 [docs/on-prem.md](docs/on-prem.md)。 ## 状态 **MVP 开发中。** 目前已提供决策记录 CRUD、CE 获取解析器、风险评分、回滚评分、事件关联、仪表板 API、Docker Compose 以及基础的 Helm chart。 ## Demo 包 每个发布版本都包含一个自托管的 demo 包，涵盖 API、Web 门户、worker、Docker Compose、Helm chart、文档和演示 GIF。 ``` make package VERSION=v1.1.0 tar -xzf dist/devopsledger-v1.1.0-demo-package.tar.gz cd devopsledger-v1.1.0-demo-package cp env.example .env DEVOPSLEDGER_VERSION=1.1.0 docker compose -f deploy/docker-compose/docker-compose.release.yml up -d ``` - API: `http://localhost:8000/health` - 当 `ENABLE_DOCS=true` 时的 API 文档: `http://localhost:8000/docs` - Web 门户: `http://localhost:3000` 请参阅 [docs/demo-package.md](docs/demo-package.md)。 **理想的评估流程：** 1. 启动发布包。 2. 打开 Web 门户和变更资源时间线。 3. 访问 API 的健康检查和文档端点。 4. 阅读架构、数据模型、安全和本地部署文档。 5. 确认默认配置：开启离线模式、关闭遥测、所有集成为可选。 ## Docker ``` docker pull ghcr.io/gerardrecinto/devopsledger/api:latest docker pull ghcr.io/gerardrecinto/devopsledger/web:latest docker pull ghcr.io/gerardrecinto/devopsledger/worker:latest ``` API 的 Dockerfile 包含 `HEALTHCHECK`，因此 Docker 和编排器无需外部探针即可检测启动失败。当 API 准备就绪时，`GET /health` 会返回 200。 ## 快速开始 ``` git clone https://github.com/gerardrecinto/devopsledger.git cd devopsledger cp .env.example .env # edit POSTGRES_PASSWORD at minimum make up # API: http://localhost:8000/health # Web: http://localhost:3000 ``` ## 开发说明 ``` make test-api # run API tests make dev # start API with hot-reload (no Docker needed) make up # start full stack via Docker Compose make down # stop make logs # tail logs make build # rebuild images ``` ## 架构 - FastAPI 后端 (`apps/api`) - PostgreSQL - 持久化存储 - Redis - 任务队列与缓存 - Next.js 前端 (`apps/web`) - 后台 worker (`apps/worker`) - Docker Compose (本地部署) - Helm chart 请参阅 [docs/architecture.md](docs/architecture.md)。 ## 许可证 MIT - 社区版现在是、且将始终保持开源。

标签：GitOps, Python, 决策记录, 基础设施管理, 搜索引擎查询, 无后门, 测试用例, 版权保护, 运维