sevoniva/Nivora
GitHub: sevoniva/Nivora
Nivora 是一个开源 DevOps 交付控制平面，用于协调和审计跨工具的交付流程，解决状态分散和审计困难的问题。
Stars: 2 | Forks: 0
# Nivora 系统
**Nivora** 是 `sevoniva` 组织下的一个开源 DevOps 交付控制平面。
该项目记录了跨流水线、发布、制品、部署、运行器、策略决策、审批、日志、事件和审计记录的交付意图和状态。其设计是围绕现有工具构建，而非取代它们。
Nivora **不是** Jenkins、Argo CD、Kubernetes、Harbor、云控制平面或扫描器。这些系统保持独立；Nivora 模型并审计交付工作流如何通过它们移动。
未来的 `v1.0.0` 文档是规划清单，并非已达到正式发布的证明。当前的真实来源是 [能力状态](docs/status/CAPABILITY_STATUS.md)，历史审计上下文见 [实施审计](docs/status/IMPLEMENTATION_AUDIT.md)。
## 当前状态
| 领域 | 状态 |
|---|---|
| PipelineRun 运行时 | 已实现本地 Shell 执行；非完整工作流引擎 |
| DeploymentRun 运行时 | 部分实现；存在 YAML 干运行、受控应用、资源清单、健康检查、差异对比、审计和 PostgreSQL 持久化基础 |
| Release 与 ReleaseExecution | 部分实现；存在顺序编排和 PostgreSQL 持久化基础 |
| Runner 协议 | 部分实现；存在令牌、心跳、认领、日志、状态和隔离配置文件；操作系统级沙箱化仍需操作员工作 |
| Kubernetes YAML | 实验性受控应用/回滚基础；无默认破坏性行为 |
| GitOps / Argo CD | 实验性规划/状态/受控同步基础；无生产 Argo 自动化 |
| Artifact / OCI | 部分实现；存在 OCI 解析和摘要基础；无完整注册表产品集成 |
| DevSecOps / 策略 | 基础；存在 noop/假扫描器路径和内置规则；无 Trivy/Cosign/SBOM 生产集成 |
| Secrets / 凭证 | 部分实现；存在元数据、脱敏、提供者骨架；生产提供者生命周期仍属未来工作 |
| Auth / RBAC | 部分实现；存在本地/令牌/OIDC 基础和路由测试；完整企业 SSO 仍属未来工作 |
| Approvals / 变更窗口 / 通知 | 基础；仅后端，无 ITSM 工作流 |
| 多云 | 仅占位符/基础资源清单；无云部署 |
| 主机部署 | 实验性规划/干运行/noop 和受控 SSH 接口 |
| Web 控制台 | 实验性最小化 UI，消费后端 API |
| 打包 | 部分实现；存在 Docker Compose、Helm、类生产值和冒烟检查 |
| 可观测性 / 审计 | 部分实现；存在诊断、指标、运行手册、审计/证据基础；生产保留/导出仍需加固 |
当前焦点：
```
keep public status accurate
keep examples and docs aligned with implemented behavior
stabilize CI, packaging, and local demo paths
continue runtime, install, restore, runner, and audit hardening
```
状态参考：
## Nivora 存在的意义
交付状态通常分散在多个系统中。
| 领域 | 常见工具 |
|---|---|
| 源码控制 | GitHub, GitLab, Gitea |
| CI 执行 | Jenkins, GitLab CI, GitHub Actions, Tekton |
| 制品存储 | Harbor, Nexus, JFrog, OCI 注册表, S3 |
| Kubernetes 交付 | kubectl, Helm, Kustomize |
| GitOps | Argo CD |
| 主机部署 | SSH, systemd, 脚本 |
| 云目标 | AWS, Aliyun, Tencent Cloud |
| 安全 | Trivy, Cosign, SBOM 工具, 策略引擎 |
| 可观测性 | OpenTelemetry, Prometheus, 日志 |
| 人工流程 | 审批, 变更窗口, 发布审计 |
问题不在于单个工具。问题在于交付意图、执行状态、审计、策略、制品可追溯性和回滚上下文通常分开存储。
Nivora 为该状态提供了一个后端控制平面模型。
## 产品定位
Nivora 是一个**交付控制平面**。它不仅是 CI 工具，也不仅是 CD 工具。
它协调：
```
source code
-> pipeline execution
-> artifact selection
-> policy evaluation
-> approval
-> deployment
-> verification
-> rollback
-> audit
-> timeline
```
Nivora 旨在回答以下操作性问题：
- 哪个提交产生了此发布？
- 部署了哪个制品？
- 谁批准了生产部署？
- 哪个运行器执行了任务？
- 哪些策略关口通过或失败？
- 哪个环境接收了此发布？
- 两次部署之间发生了什么变化？
- 哪些日志、事件和审计记录属于此交付？
- 此次部署能否安全回滚？
- 哪些外部系统参与了此次交付？
## Nivora 价值图
此图显示了外部系统、Nivora 控制平面、执行机制和交付记录之间的预期边界。
```
flowchart LR
subgraph A["External Delivery Systems"]
A1["Git Providers
GitHub / GitLab / Gitea"] A2["Artifact Registries
Harbor / Nexus / OCI / S3"] A3["Delivery Targets
Hosts / Kubernetes / Argo CD / Cloud"] A4["Security Tools
Trivy / Cosign / Policy Engines"] A5["Human Process
Approval / Change Window / Audit"] end subgraph B["Nivora Delivery Control Plane"] B1["Application & Environment Model"] B2["Pipeline & Release Orchestration"] B3["Runner & Executor Coordination"] B4["Policy Gates & Approval"] B5["Artifact & Version Traceability"] B6["Audit, Events & Timeline"] B7["Open APIs & Future Visualization"] end subgraph C["Execution Plane"] C1["Host Runner"] C2["Kubernetes Runner"] C3["GitOps Runner"] C4["Cloud Runner"] C5["Local / Dev Runner"] end subgraph D["Delivery Records"] D1["Repeatable PipelineRun"] D2["Auditable DeploymentRun"] D3["Immutable Artifact Release"] D4["Controlled Rollback"] D5["Observable Delivery Timeline"] D6["Multi-Target Delivery"] end A1 --> B A2 --> B A3 --> B A4 --> B A5 --> B B --> C C --> D B --> D ``` ## Nivora 是什么 Nivora 是一个交付控制平面。它协调： - 流水线执行 - 发布规划 - 部署执行 - 运行器分配 - 执行器选择 - 制品可追溯性 - 策略评估 - 审批流程 - 审计记录 - 运行时事件 - 交付时间线 - 可视化 API 读取模型 Nivora 起初作为**模块化单体**，包含多个二进制文件： ``` nivora-server nivora-worker nivora-runner nivora CLI ``` 这使项目易于理解，同时保留了通向未来服务提取的路径。 ## Nivora 不是什么 Nivora 不是： - Jenkins 克隆 - Argo CD 替代品 - 仅限 Kubernetes 的平台 - 特定云提供商系统 - 前端优先项目 - 黑盒自动化工具 - 声称每个建模的集成都已生产就绪 Nivora 应通过明确的端口和适配器与现有系统集成。 ## 目标架构 目标架构将**控制平面**与**执行平面**分离。 控制平面拥有状态、编排、策略、审计、API 和集成配置。执行平面拥有任务执行、日志、心跳和运行时结果。 ``` flowchart TB U1["Users / Maintainers"] U2["CLI"] U3["Future Web UI"] U4["Git Webhooks"] subgraph CP["Control Plane"] API["API Server
REST / OpenAPI"] AUTH["AuthN / AuthZ
future OIDC / RBAC"] ORCH["Workflow Orchestrator
PipelineRun / DeploymentRun"] POLICY["Policy Engine
Gates / Approval / Windows"] INTEG["Integration Manager
SCM / Artifact / Cloud / Secret"] AUDIT["Audit Service
Who did what, when, why"] EVENT["Event Service
CloudEvents-style"] LOGIDX["Log Index
LogChunk metadata"] end subgraph STATE["State & Storage"] DB[("PostgreSQL
source of truth")] OBJ[("Object Store
S3 / MinIO / local")] BUS[("Event Bus
memory now
NATS / Redis later")] end subgraph EP["Execution Plane"] RM["Runner Manager"] R1["Host Runner"] R2["Kubernetes Runner"] R3["GitOps Runner"] R4["Cloud Runner"] R5["Local Runner"] EX1["Shell Executor"] EX2["SSH Executor"] EX3["Kubernetes Job Executor"] EX4["YAML / Helm Executor"] EX5["Argo CD Executor"] EX6["Webhook Executor"] end subgraph EXT["External Systems"] SCM["SCM
GitHub / GitLab / Gitea"] ART["Artifact Registry
Harbor / Nexus / OCI / S3"] K8S["Kubernetes
YAML / Helm / Kustomize"] ARGO["Argo CD
GitOps sync"] HOST["Hosts
VM / Bare Metal"] CLOUD["Cloud Providers
AWS / Aliyun / Tencent"] SEC["Security Tools
Trivy / Cosign / SBOM"] OBS["Observability
OpenTelemetry / Prometheus / Logs"] end U1 --> API U2 --> API U3 -. future .-> API U4 --> API API --> AUTH API --> ORCH API --> INTEG API --> AUDIT API --> EVENT ORCH --> POLICY ORCH --> RM ORCH --> DB AUDIT --> DB EVENT --> BUS LOGIDX --> DB LOGIDX --> OBJ RM --> R1 RM --> R2 RM --> R3 RM --> R4 RM --> R5 R1 --> EX1 R1 --> EX2 R2 --> EX3 R2 --> EX4 R3 --> EX5 R4 --> EX6 R5 --> EX1 INTEG --> SCM INTEG --> ART INTEG --> CLOUD INTEG --> SEC EX2 --> HOST EX3 --> K8S EX4 --> K8S EX5 --> ARGO EX6 --> CLOUD EVENT --> OBS ``` ## 架构原则 ### 控制平面和执行平面是分离的 控制平面拥有 API、状态、编排、策略、审计、集成配置和事件时间线。执行平面拥有任务执行、日志、心跳和运行时结果报告。 API 服务器不应直接执行部署任务。 ### Runner 和 Executor 是不同的 ``` Runner = who executes Executor = how execution happens ``` | Runner | Executor | |---|---| | 本地 Runner | Shell 执行器 | | 主机 Runner | SSH 执行器 | | Kubernetes Runner | Kubernetes Job 执行器 | | GitOps Runner | Argo CD 执行器 | | 云 Runner | Webhook / 云适配器 | 这种分离允许 Nivora 支持多种执行环境而无需重写核心编排逻辑。 ### GitOps 是一种部署模式 Nivora 支持 GitOps，但 GitOps 并非产品的全部。 未来的部署模式包括主机部署、原始 Kubernetes YAML、Helm、Kustomize、Argo CD GitOps、基于 Webhook 的交付和特定云提供商的交付。 ### 端口和适配器优先 外部系统必须通过稳定的接口集成： ``` SCMProvider ArtifactProvider CloudProvider Executor WorkflowRuntime SecretProvider NotificationProvider PolicyEngine EventBus ObjectStore ``` 核心用例应依赖于能力，而非具体供应商。 ### 制品应该是不可变的 发布应尽可能指向不可变的制品：镜像摘要、不可变版本、已签名制品和 SBOM 引用。避免使用 `latest` 标签、部署期间的隐式重建以及未跟踪的制品变更。 ### 审计不是可选项 重要的交付操作必须可审计：流水线启动、任务分配、制品选择、批准或拒绝、部署启动、回滚执行、策略违规检测、运行器注册和凭证使用。 审计记录不得包含密钥值。 ### 没有虚假的生产就绪性声明 Nivora 应明确说明当前存在的功能和目标架构。早期阶段不得声称生产就绪、集成完整、持久化调度或尚未实现和验证的安全保证。 ## 端到端交付流程 这是 Nivora 设计所围绕的长期流程。早期阶段仅实现基于 Shell 的 PipelineRun 子集：定义解析、排队运行创建、本地运行器执行、日志、事件、审计记录、重试、超时、取消和时间线查询。 ``` flowchart TB START["Git Push / Manual Trigger / API Trigger"] INGEST["Trigger Ingestion"] PLAN["Create PipelineRun"] SNAPSHOT["Execution Snapshot"] POLICY{"Pre-check Policy Gates"} DENIED["Stop and record policy result"] QUEUE["Queue PipelineRun"] WORKER["Worker Picks Run"] RUNTIME["Build Runtime Plan"] SELECT{"Select Runner"} RUNNER["Runner"] EXECUTOR["Executor"] LOGS["Capture Logs"] STATUS["Persist Status Transitions"] EVENTS["Emit Events"] AUDIT["Write Audit Records"] APPROVAL{"Approval Required?"} DEPLOY["Create DeploymentRun"] MODE{"Deployment Mode"} VERIFY["Verify"] ROLLBACK{"Rollback Needed?"} RB["Rollback"] TIMELINE["Unified Timeline"] START --> INGEST --> PLAN --> SNAPSHOT --> POLICY POLICY -->|Denied| DENIED --> TIMELINE POLICY -->|Allowed| QUEUE --> WORKER --> RUNTIME --> SELECT SELECT --> RUNNER --> EXECUTOR --> LOGS --> STATUS --> EVENTS --> AUDIT AUDIT --> APPROVAL APPROVAL -->|No| DEPLOY APPROVAL -->|Yes| DEPLOY DEPLOY --> MODE --> VERIFY --> ROLLBACK ROLLBACK -->|Yes| RB --> TIMELINE ROLLBACK -->|No| TIMELINE ``` ## PipelineRun 运行时模型 这是 Nivora 正在构建的第一个执行基础。当前实现仅限于最小化的基于 Shell 的 PipelineRun 执行。 ``` sequenceDiagram autonumber participant User as User / CLI / API participant API as API Server participant UC as PipelineRun Usecase participant Repo as Runtime Repositories participant Worker as Worker participant Runner as Runner participant Exec as Executor participant Event as EventBus participant Audit as AuditLog User->>API: POST /api/v1/pipeline-runs API->>UC: CreatePipelineRun(spec) UC->>Repo: Persist PipelineRun, StageRun, JobRun, StepRun UC->>Event: emit pipeline.run.created UC->>Audit: record PipelineRun created UC-->>API: PipelineRun ID Worker->>Repo: Poll queued PipelineRun Worker->>Repo: PipelineRun -> Running Worker->>Event: emit pipeline.run.started Worker->>Audit: record PipelineRun started Worker->>Runner: Assign JobRun Runner->>Exec: Run step Exec-->>Runner: stdout / stderr / exit code Runner->>Repo: Persist LogChunks Runner->>Repo: StepRun / JobRun status Worker->>Repo: PipelineRun final status Worker->>Event: emit completed or failed Worker->>Audit: record lifecycle result User->>API: GET /api/v1/pipeline-runs/{id}/timeline API->>Repo: Query ordered runtime events API-->>User: Timeline ``` ## PipelineRun 状态模型 ``` stateDiagram-v2 [*] --> Pending Pending --> Queued Queued --> Running Running --> Paused Paused --> Running Running --> Succeeded Running --> Failed Running --> Timeout Pending --> Canceled Queued --> Canceled Running --> Canceled Paused --> Canceled Failed --> Retrying Retrying --> Queued Succeeded --> [*] Failed --> [*] Timeout --> [*] Canceled --> [*] ``` ## Runner 和 Executor 模型 ``` flowchart TB CP["Control Plane"] --> RM["Runner Manager"] RM --> LOCAL["Local Runner"] RM --> HOST["Host Runner"] RM --> K8S["Kubernetes Runner"] RM --> GITOPS["GitOps Runner"] RM --> CLOUD["Cloud Runner"] LOCAL --> SHELL["Shell Executor"] HOST --> SSH["SSH Executor"] K8S --> KJOB["Kubernetes Job Executor"] K8S --> HYAML["Helm / YAML Executor"] GITOPS --> ARGO["Argo CD Executor"] CLOUD --> WEBHOOK["Webhook / Cloud Executor"] SHELL --> RESULT["Execution Result"] SSH --> RESULT KJOB --> RESULT HYAML --> RESULT ARGO --> RESULT WEBHOOK --> RESULT RESULT --> CP ``` ## 部署模型 部署执行是目标架构。在当前阶段，它并未作为完整的生产部署引擎实现。 ``` flowchart TB APP["Application"] ENV["Environment"] REL["Release"] DR["DeploymentRun"] TARGET{"ReleaseTarget Type"} APP --> ENV --> REL --> DR --> TARGET TARGET --> HOST["HostTarget"] TARGET --> K8S["KubernetesTarget"] TARGET --> HELM["HelmTarget"] TARGET --> KUSTOMIZE["KustomizeTarget"] TARGET --> ARGO["ArgoCDTarget"] TARGET --> CLOUD["CloudTarget"] TARGET --> WEBHOOK["WebhookTarget"] HOST --> SSH["SSH Executor"] K8S --> YAML["YAML Apply Executor"] HELM --> HEX["Helm Executor"] KUSTOMIZE --> KREN["Kustomize Renderer"] ARGO --> AEX["Argo CD Executor"] CLOUD --> CAD["Cloud Adapter"] WEBHOOK --> WEX["Webhook Executor"] SSH --> VERIFY["Verify"] YAML --> VERIFY HEX --> VERIFY KREN --> VERIFY AEX --> VERIFY CAD --> VERIFY WEX --> VERIFY VERIFY --> RESULT{"Result"} RESULT -->|Healthy| SUCCESS["Deployment Succeeded"] RESULT -->|Unhealthy| ROLLBACK["Rollback Plan"] ``` ## 集成模型 所有外部系统都应通过端口和适配器连接。下面列出的适配器名称是目标集成方向，除非明确记录为已实现。 ``` flowchart LR subgraph CORE["Core Use Cases"] PIPE["Pipeline Usecase"] DEPLOY["Deployment Usecase"] ARTUC["Artifact Usecase"] POLICYUC["Policy Usecase"] RUNUC["Runner Usecase"] end subgraph PORTS["Ports"] SCM["SCMProvider"] ART["ArtifactProvider"] CLOUD["CloudProvider"] EXEC["Executor"] WF["WorkflowRuntime"] SECRET["SecretProvider"] POLICY["PolicyEngine"] BUS["EventBus"] OBJ["ObjectStore"] end subgraph ADAPTERS["Adapters"] SCMAD["GitHub / GitLab / Gitea"] ARTAD["Harbor / Nexus / OCI / S3"] CLOUDAD["AWS / Aliyun / Tencent"] EXECAD["Shell / SSH / K8s Job / Argo CD"] SECRETAD["Built-in / Vault / K8s Secret"] POLICYAD["Built-in / OPA future"] BUSAD["Memory / NATS future"] OBJAD["Local / MinIO / S3"] end CORE --> PORTS SCM --> SCMAD ART --> ARTAD CLOUD --> CLOUDAD EXEC --> EXECAD WF --> BUSAD SECRET --> SECRETAD POLICY --> POLICYAD BUS --> BUSAD OBJ --> OBJAD ``` ## 可观测性与审计模型 ``` flowchart TB RUN["PipelineRun / DeploymentRun"] RUN --> LOGS["Logs"] RUN --> EVENTS["Events"] RUN --> AUDIT["AuditLog"] RUN --> METRICS["Metrics"] RUN --> TRACES["Traces"] LOGS --> TL["Unified Timeline"] EVENTS --> TL AUDIT --> TL METRICS --> DASH["Future Dashboards"] TRACES --> DASH TL --> API["API / CLI / Future Web UI"] DASH --> API ``` ## 核心概念 | 概念 | 含义 | |---|---| | Application | 由 Nivora 管理的产品或服务 | | Environment | 交付上下文，如开发、测试、生产或自定义目标组 | | ReleaseTarget | 具体的部署目标，如主机组、Kubernetes 集群、Argo CD 应用、云目标或 Webhook 目标 | | Pipeline | 阶段、任务和步骤的可复用定义 | | PipelineRun | 一次 Pipeline 的执行 | | StageRun | 一个阶段的执行记录 | | JobRun | 一个任务的执行记录 | | StepRun | 一个步骤的执行记录 | | Release | 版本化的交付意图，通常关联到不可变的制品 | | DeploymentRun | 一次针对目标的发布或部署计划执行 | | Runner | 接收和执行任务的组件 | | Executor | Runner 用于执行工作的机制 | | Artifact | 构建产出，如镜像、jar 包、二进制文件、Chart 包或软件包 | | Artifact Registry | 存储制品的系统 | | Policy | 可以允许、拒绝或要求批准的关口 | | AuditLog | 重要操作的持久化记录 | | Event | 交付生命周期中发出的运行时信号 | | LogChunk | 有序的 stdout、stderr 或系统日志片段 | ## 仓库布局 ``` nivora/ cmd/ nivora-server/ nivora-worker/ nivora-runner/ nivora/ internal/ app/ domain/ usecase/ ports/ adapters/ infra/ api/ api/ openapi/ asyncapi/ proto/ configs/ deployments/ examples/ docs/ scripts/ test/ AGENTS.md PROJECT_CHARTER.md README.md ROADMAP.md CONTRIBUTING.md ``` | 目录 | 用途 | |---|---| | `cmd/` | 仅存放二进制入口点 | | `internal/domain/` | 纯领域概念和状态 | | `internal/usecase/` | 业务编排 | | `internal/ports/` | 外部能力接口 | | `internal/adapters/` | 端口的实现 | | `internal/infra/` | 技术基础设施 | | `internal/api/` | HTTP / gRPC 传输层 | | `api/` | OpenAPI, AsyncAPI, proto 定义 | | `docs/` | 架构、路线图、概念、社区文档 | | `examples/` | 示例流水线和部署规范 | ## 快速开始 ### 前置条件 - Go - Make - Docker (可选，用于本地 compose) - PostgreSQL (可选，取决于运行时模式) ### 构建 ``` make build ``` ### 测试 ``` make test ``` ### 验证 ``` make verify ``` ### 打包 ``` make docker-build make helm-template make helm-lint ``` 打包文档： - [Docker Compose 安装](docs/operations/install-docker-compose.md) - [Kubernetes 安装](docs/operations/install-kubernetes.md) - [配置](docs/operations/configuration.md) - [性能与负载测试](docs/operations/performance.md) - [备份与恢复](docs/operations/backup-restore.md) - [高可用与灾难恢复](docs/operations/ha-disaster-recovery.md) ### 冒烟测试 ``` make smoke-local make smoke-api ``` ### 运行服务器 ``` make run-server ``` ### 运行 Web UI ``` make run-web ``` Web 控制台位于 `web/` 目录下，消费现有的运行时和 `/api/v1/visualization/*` 后端 API。它是第 6.4 阶段的最小化基础，并非完整的前端产品。 ### 健康检查 ``` curl http://localhost:8080/healthz curl http://localhost:8080/readyz curl http://localhost:8080/api/v1/version curl http://localhost:8080/api/v1/system/runtime curl http://localhost:8080/api/v1/system/diagnostics curl http://localhost:8080/metrics ``` `/readyz` 和 `/api/v1/system/diagnostics` 包含针对数据库、对象存储、事件总线、Outbox 恢复和运行器重连状态的轻量级依赖检查。 ### 运行 Worker ``` make run-worker ``` ### 运行 Runner ``` make run-runner ``` ### 命令行界面 ``` go run ./cmd/nivora version go run ./cmd/nivora pipeline run --local examples/pipelines/simple-shell.yaml go run ./cmd/nivora pipeline get --server http://localhost:8080
go run ./cmd/nivora pipeline logs --server http://localhost:8080
go run ./cmd/nivora pipeline timeline --server http://localhost:8080
go run ./cmd/nivora deployment plan --local examples/deployments/yaml-dry-run.yaml
go run ./cmd/nivora deployment dry-run --local examples/deployments/yaml-dry-run.yaml
go run ./cmd/nivora deployment apply --local examples/deployments/yaml-apply-local.yaml --confirm
go run ./cmd/nivora deployment host plan --file examples/deployments/host-dry-run.yaml --local
go run ./cmd/nivora deployment host run --file examples/deployments/host-dry-run.yaml --local
go run ./cmd/nivora release plan --file examples/releases/multi-target-release.yaml --local
go run ./cmd/nivora release deploy --file examples/releases/sequential-release.yaml --local
go run ./cmd/nivora cloud providers --local
go run ./cmd/nivora plugins list --local
go run ./cmd/nivora plugins inspect artifact-oci --local
go run ./cmd/nivora plugins validate --local --file examples/plugins/templates/scanner-plugin.yaml
```
## 本地开发
Nivora 通过 Makefile、docker-compose、本地对象存储、内存事件总线、Shell 执行器和示例流水线支持本地开发。
此仓库在本地工具中使用中立的默认 Go 代理：
```
GOPROXY=https://proxy.golang.org,direct
```
中国的开发者可以无需更改项目默认设置即可覆盖它：
```
GOPROXY=https://goproxy.cn,direct make verify
```
或：
```
export GOPROXY=https://goproxy.cn,direct
make verify
```
## 示例流水线
```
apiVersion: nivora.io/v1alpha1
kind: Pipeline
metadata:
name: hello-shell
spec:
stages:
- name: build
jobs:
- name: echo
executor: shell
steps:
- name: say-hello
run: echo "hello from nivora"
```
本地运行：
```
go run ./cmd/nivora pipeline run --local examples/pipelines/simple-shell.yaml
```
## 示例 YAML 部署干运行
当前第 2 阶段基础支持非破坏性的 YAML 部署规划和干运行验证，以及用于运行时测试的显式本地无操作应用。它渲染静态清单，验证其基本结构，创建 DeploymentPlan，记录资源清单，针对绑定制品验证清单镜像，记录日志/事件/审计/时间线数据，并且默认情况下不会将资源应用到集群。
```
apiVersion: nivora.io/v1alpha1
kind: Deployment
metadata:
name: demo-yaml-deployment
spec:
application: demo-springboot
environment: dev
target:
type: kubernetes-yaml
name: dev-kind
namespace: default
manifests:
- examples/yaml/configmap.yaml
- examples/yaml/deployment.yaml
- examples/yaml/service.yaml
options:
dryRun: true
apply: false
```
本地运行：
```
go run ./cmd/nivora deployment plan --local examples/deployments/yaml-dry-run.yaml
go run ./cmd/nivora deployment dry-run --local examples/deployments/yaml-dry-run.yaml
```
显式本地应用需要单独的命令和确认：
```
go run ./cmd/nivora deployment apply --local examples/deployments/yaml-apply-local.yaml --confirm
```
默认的本地应用路径使用安全的无操作清单客户端。生产 Kubernetes 应用语义、Helm、Kustomize、Argo CD、云提供商、远程主机部署和注册表集成仍属未来工作。
## 示例主机部署干运行
第 8.1 阶段加固了安全的主机部署基础。它可以为将二进制包部署到版本化发布目录、切换符号链接、检查 HTTP/TCP/命令健康状态、运行批处理和准备受控符号链接回滚来构建计划。默认运行时使用 noop 主机执行器，不执行远程 SSH。
```
go run ./cmd/nivora deployment host plan --file examples/deployments/host-dry-run.yaml --local
go run ./cmd/nivora deployment host run --file examples/deployments/host-dry-run.yaml --local
```
除非明确配置了适配器传输层并具有凭证引用、确认和允许标志，否则远程主机部署保持禁用状态。
## 示例多目标发布
第 2.7 阶段增加了本地 ReleasePlan / ReleaseExecution 基础。它可以规划跨多个目标的 Release，并通过目标级 DeploymentRun 或占位符目标顺序执行安全目标。
```
go run ./cmd/nivora release plan --file examples/releases/multi-target-release.yaml --local
go run ./cmd/nivora release deploy --file examples/releases/sequential-release.yaml --local
```
这不是生产工作流引擎。并行执行、持久化审批、主机/云目标和生产 GitOps 自动化仍属未来工作。
通过 API 运行最小化的 Shell PipelineRun：
```
curl -X POST http://localhost:8080/api/v1/pipeline-runs \
-H 'Content-Type: application/json' \
-d '{
"apiVersion": "nivora.io/v1alpha1",
"kind": "Pipeline",
"metadata": {"name": "hello-shell"},
"spec": {
"stages": [{
"name": "build",
"jobs": [{
"name": "echo",
"executor": "shell",
"steps": [{"name": "say-hello", "run": "echo hello from nivora"}]
}]
}]
}
}'
```
未实现的 API 组返回结构化响应，而非虚假数据：
```
{
"code": "not_implemented",
"message": "This endpoint is reserved for a future phase.",
"path": "/api/v1/integrations"
}
```
## 事件
Nivora 使用 CloudEvents 风格的事件信封。
```
{
"specversion": "1.0",
"id": "evt_01HX",
"type": "devops.pipeline.run.started",
"source": "/projects/example/pipelines/hello-shell",
"subject": "pipelineRun/pr_123",
"time": "2026-05-18T10:00:00Z",
"datacontenttype": "application/json",
"data": {
"pipelineRunId": "pr_123",
"status": "Running"
}
}
```
OpenAPI 定义位于 `api/openapi/openapi.yaml`。AsyncAPI 定义位于 `api/asyncapi/asyncapi.yaml`。
核心 API 组包括：
```
/api/v1/orgs
/api/v1/projects
/api/v1/applications
/api/v1/environments
/api/v1/repositories
/api/v1/artifact-registries
/api/v1/pipelines
/api/v1/pipeline-runs
/api/v1/jobs
/api/v1/releases
/api/v1/deployments
/api/v1/runners
/api/v1/approvals
/api/v1/policies
/api/v1/audit-logs
/api/v1/events
/api/v1/logs
/api/v1/integrations
/api/v1/visualization
```
## 路线图
```
flowchart LR
P0["Phase 0
Backend Skeleton"] P05["Phase 0.5
Guardrails"] P06["Phase 0.6
Public Planning"] P1["Phase 1
Minimal Runtime"] P15["Phase 1.5
Durable Runtime Foundation"] P16["Phase 1.6
Runtime DX & Acceptance"] P2["Phase 2.0
YAML Planning Foundation"] P21["Phase 2.1
Kubernetes YAML Runtime"] P22["Phase 2.2
Artifact & Release Binding"] P23["Phase 2.3
GitOps & Argo CD Foundation"] P24["Phase 2.4
Kubernetes Inventory & Rollback Foundation"] P25["Phase 2.5
OCI Digest Resolution"] P26["Phase 2.6
Argo CD Guarded Sync"] P27["Phase 2.7
Release Orchestration"] P30["Phase 3.0
DevSecOps Foundation"] P31["Phase 3.1
Secret & Credential Foundation"] P32["Phase 3.2
Auth & RBAC Foundation"] P33["Phase 3.3
Approvals & Change Windows"] P34["Phase 3.4
Multi-cloud Inventory"] P35["Phase 3.5
Host Deployment Foundation"] P36["Phase 3.6
Durable Runner Runtime"] P3["Future Phase 3
Multi-cloud & DevSecOps"] P40["Phase 4.0
Visualization Backend APIs"] P41["Phase 4.1
Web UI Foundation"] P4["Future Phase 4
Frontend Visualization"] P0 --> P05 --> P06 --> P1 --> P15 --> P16 --> P2 --> P21 --> P22 --> P23 --> P24 --> P25 --> P26 --> P27 --> P30 --> P31 --> P32 --> P33 --> P34 --> P35 --> P36 --> P3 --> P40 --> P41 --> P4 ``` 详情见 [ROADMAP.md](ROADMAP.md) 和 [docs/roadmap/overview.md](docs/roadmap/overview.md)。 ## 贡献图谱 ``` flowchart TB C["Contributor"] C --> G1["Good First Contributions"] C --> G2["Intermediate Contributions"] C --> G3["Advanced Contributions"] C --> G4["Requires RFC"] G1 --> D1["Documentation"] G1 --> D2["Examples"] G1 --> D3["Tests"] G1 --> D4["CLI polish"] G1 --> D5["API schema cleanup"] G2 --> I1["Shell executor improvements"] G2 --> I2["Memory event bus"] G2 --> I3["Local object store"] G2 --> I4["Config validation"] G2 --> I5["Pipeline state tests"] G3 --> A1["PipelineRun state machine"] G3 --> A2["Runner protocol"] G3 --> A3["Log streaming"] G3 --> A4["Persistence"] G3 --> A5["Kubernetes Job executor"] G3 --> A6["YAML renderer"] G3 --> A7["Argo CD adapter"] G3 --> A8["Policy engine"] G4 --> R1["Runner protocol changes"] G4 --> R2["Workflow runtime changes"] G4 --> R3["Database model changes"] G4 --> R4["Cloud provider adapters"] G4 --> R5["Kubernetes / Argo CD integration design"] G4 --> R6["Plugin system changes"] G4 --> R7["Security model changes"] G4 --> R8["Public API breaking changes"] ``` 贡献前请阅读： - [AGENTS.md](AGENTS.md) - [CONTRIBUTING.md](CONTRIBUTING.md) - [PROJECT_CHARTER.md](PROJECT_CHARTER.md) - [docs/README.md](docs/README.md) - [docs/rfcs/README.md](docs/rfcs/README.md) - [docs/architecture/architecture-contract.md](docs/architecture/architecture-contract.md) - [docs/architecture/module-boundaries.md](docs/architecture/module-boundaries.md) - [docs/engineering/testing-policy.md](docs/engineering/testing-policy.md) - [docs/engineering/dependency-policy.md](docs/engineering/dependency-policy.md) 基本期望： - 保持变更范围小 - 遵守架构边界 - 不添加投机性抽象 - 不提交密钥 - 不声称生产就绪 - 架构变更时更新文档 - 公共行为变更时更新 OpenAPI / AsyncAPI - 为行为变更添加测试 ## 贡献者自动化 自动化编码工具和人类贡献者使用相同的仓库规则。规范指导文件是 [AGENTS.md](AGENTS.md)。 特定工具的指导文件应指向 `AGENTS.md`，而不是定义冲突的行为。所有变更必须遵守架构边界、阶段边界、依赖策略、测试策略、安全基线和文档一致性。 ## 验证 运行完整的验证套件： ``` make verify ``` 预期的检查包括： ``` gofmt check go mod tidy check go vet ./... go test ./... go build ./cmd/nivora-server go build ./cmd/nivora-worker go build ./cmd/nivora-runner go build ./cmd/nivora architecture verification secret scanning ``` ## 安全 Nivora 不得提交或暴露密钥。 不要提交令牌、密码、私钥、kubeconfig 文件、云凭证、注册表凭证或看起来真实的伪造凭证。密钥值不得被记录、通过正常 API 返回、存储在审计记录中、嵌入示例或嵌入测试中。 参见 [SECURITY.md](SECURITY.md) 和 [docs/engineering/security-baseline.md](docs/engineering/security-baseline.md)。 第 3.0 阶段增加了本地 DevSecOps 基础： ``` go run ./cmd/nivora security scan artifact registry.example.com/demo/app:latest --local go run ./cmd/nivora security scan manifest examples/security/manifest-privileged-warning.yaml --local go run ./cmd/nivora policy evaluate --subject registry.example.com/demo/app:latest ``` 这些命令使用 noop/假友好的扫描器基础和内置策略关口。Trivy、Cosign、SBOM 生成、OPA、Kyverno、Gatekeeper 和生产安全自动化仍属未来工作。 第 3.1 阶段增加了 SecretRef 和 Credential 元数据： ``` go run ./cmd/nivora secret put --name local-registry-token --value-env NIVORA_TOKEN go run ./cmd/nivora secret provider validate go run ./cmd/nivora credential create --file examples/credentials/registry-credential.yaml --local ``` 密钥值仅在创建和轮换边界时被接受，并且不会通过正常 API 返回。内置提供者仅用于开发。第 7.1 阶段增加了 Vault 和 Kubernetes Secret 适配器基础以及云 KMS 占位符；生产外部密钥存储仍属未来工作。 第 7.0 阶段加固了本地 Auth 和 RBAC 基础： ``` go run ./cmd/nivora auth whoami go run ./cmd/nivora auth permissions go run ./cmd/nivora auth service-account create --name ci --role developer go run ./cmd/nivora auth token create --subject-id
```
开发认证不是生产认证。静态令牌模式从环境变量读取令牌值。OIDC 是提供者配置的后端基础工作；完整的浏览器 SSO 和提供者生命周期操作仍属未来工作。
第 7.2 阶段增加了多租户和配额基础：
```
go run ./cmd/nivora quota view --scope-type project --scope-id demo
go run ./cmd/nivora usage summary --scope-type project --scope-id demo
```
范围化的 API 令牌可以约束到组织/项目/环境风格的边界，配额读取模型暴露了并发、运行器、制品、日志存储和速率限制基础。持久化的分布式配额执行仍属未来工作。
第 7.3 阶段增加了合规审计和证据基础：
```
go run ./cmd/nivora audit search --subject
go run ./cmd/nivora evidence export pipelineRun --format markdown
```
证据包收集安全的发布、制品、审批、策略、安全、部署、日志引用、事件和审计上下文。类似密钥的值在导出前被脱敏；不可变的外部审计存储和保留执行作业仍属未来工作。
## 文档
| 文档 | 用途 |
|---|---|
| [PROJECT_CHARTER.md](PROJECT_CHARTER.md) | 项目目的和原则 |
| [ROADMAP.md](ROADMAP.md) | 高层路线图 |
| [docs/README.md](docs/README.md) | 文档索引 |
| [docs/architecture/](docs/architecture/overview.md) | 架构模型 |
| [docs/concepts/](docs/concepts/overview.md) | 核心概念 |
| [docs/product/](docs/product/vision.md) | 产品规划 |
| [docs/community/](docs/community/governance.md) | 贡献与治理 |
| [docs/rfcs/](docs/rfcs/README.md) | RFC 流程 |
| [docs/adr/](docs/adr/0001-use-go-as-primary-language.md) | 架构决策记录 |
| [AGENTS.md](AGENTS.md) | 自动化与贡献规则 |
## 设计北极星
Nivora 的构建旨在使交付系统更加连贯。它不假设单一工具、单一云、单一运行时或单一部署模型。
长期目标是提供一个交付控制平面，其中：
```
pipelines are repeatable
releases are artifact-based
deployments are auditable
policies are explicit
runners are isolated
integrations are replaceable
events are observable
rollback is traceable
```
Nivora 从小处起步。第一个里程碑不是支持所有工具。第一个里程碑是构建正确的基础。
## 许可证
Nivora 使用 Apache License 2.0 许可。参见 [LICENSE](LICENSE)。
GitHub / GitLab / Gitea"] A2["Artifact Registries
Harbor / Nexus / OCI / S3"] A3["Delivery Targets
Hosts / Kubernetes / Argo CD / Cloud"] A4["Security Tools
Trivy / Cosign / Policy Engines"] A5["Human Process
Approval / Change Window / Audit"] end subgraph B["Nivora Delivery Control Plane"] B1["Application & Environment Model"] B2["Pipeline & Release Orchestration"] B3["Runner & Executor Coordination"] B4["Policy Gates & Approval"] B5["Artifact & Version Traceability"] B6["Audit, Events & Timeline"] B7["Open APIs & Future Visualization"] end subgraph C["Execution Plane"] C1["Host Runner"] C2["Kubernetes Runner"] C3["GitOps Runner"] C4["Cloud Runner"] C5["Local / Dev Runner"] end subgraph D["Delivery Records"] D1["Repeatable PipelineRun"] D2["Auditable DeploymentRun"] D3["Immutable Artifact Release"] D4["Controlled Rollback"] D5["Observable Delivery Timeline"] D6["Multi-Target Delivery"] end A1 --> B A2 --> B A3 --> B A4 --> B A5 --> B B --> C C --> D B --> D ``` ## Nivora 是什么 Nivora 是一个交付控制平面。它协调： - 流水线执行 - 发布规划 - 部署执行 - 运行器分配 - 执行器选择 - 制品可追溯性 - 策略评估 - 审批流程 - 审计记录 - 运行时事件 - 交付时间线 - 可视化 API 读取模型 Nivora 起初作为**模块化单体**，包含多个二进制文件： ``` nivora-server nivora-worker nivora-runner nivora CLI ``` 这使项目易于理解，同时保留了通向未来服务提取的路径。 ## Nivora 不是什么 Nivora 不是： - Jenkins 克隆 - Argo CD 替代品 - 仅限 Kubernetes 的平台 - 特定云提供商系统 - 前端优先项目 - 黑盒自动化工具 - 声称每个建模的集成都已生产就绪 Nivora 应通过明确的端口和适配器与现有系统集成。 ## 目标架构 目标架构将**控制平面**与**执行平面**分离。 控制平面拥有状态、编排、策略、审计、API 和集成配置。执行平面拥有任务执行、日志、心跳和运行时结果。 ``` flowchart TB U1["Users / Maintainers"] U2["CLI"] U3["Future Web UI"] U4["Git Webhooks"] subgraph CP["Control Plane"] API["API Server
REST / OpenAPI"] AUTH["AuthN / AuthZ
future OIDC / RBAC"] ORCH["Workflow Orchestrator
PipelineRun / DeploymentRun"] POLICY["Policy Engine
Gates / Approval / Windows"] INTEG["Integration Manager
SCM / Artifact / Cloud / Secret"] AUDIT["Audit Service
Who did what, when, why"] EVENT["Event Service
CloudEvents-style"] LOGIDX["Log Index
LogChunk metadata"] end subgraph STATE["State & Storage"] DB[("PostgreSQL
source of truth")] OBJ[("Object Store
S3 / MinIO / local")] BUS[("Event Bus
memory now
NATS / Redis later")] end subgraph EP["Execution Plane"] RM["Runner Manager"] R1["Host Runner"] R2["Kubernetes Runner"] R3["GitOps Runner"] R4["Cloud Runner"] R5["Local Runner"] EX1["Shell Executor"] EX2["SSH Executor"] EX3["Kubernetes Job Executor"] EX4["YAML / Helm Executor"] EX5["Argo CD Executor"] EX6["Webhook Executor"] end subgraph EXT["External Systems"] SCM["SCM
GitHub / GitLab / Gitea"] ART["Artifact Registry
Harbor / Nexus / OCI / S3"] K8S["Kubernetes
YAML / Helm / Kustomize"] ARGO["Argo CD
GitOps sync"] HOST["Hosts
VM / Bare Metal"] CLOUD["Cloud Providers
AWS / Aliyun / Tencent"] SEC["Security Tools
Trivy / Cosign / SBOM"] OBS["Observability
OpenTelemetry / Prometheus / Logs"] end U1 --> API U2 --> API U3 -. future .-> API U4 --> API API --> AUTH API --> ORCH API --> INTEG API --> AUDIT API --> EVENT ORCH --> POLICY ORCH --> RM ORCH --> DB AUDIT --> DB EVENT --> BUS LOGIDX --> DB LOGIDX --> OBJ RM --> R1 RM --> R2 RM --> R3 RM --> R4 RM --> R5 R1 --> EX1 R1 --> EX2 R2 --> EX3 R2 --> EX4 R3 --> EX5 R4 --> EX6 R5 --> EX1 INTEG --> SCM INTEG --> ART INTEG --> CLOUD INTEG --> SEC EX2 --> HOST EX3 --> K8S EX4 --> K8S EX5 --> ARGO EX6 --> CLOUD EVENT --> OBS ``` ## 架构原则 ### 控制平面和执行平面是分离的 控制平面拥有 API、状态、编排、策略、审计、集成配置和事件时间线。执行平面拥有任务执行、日志、心跳和运行时结果报告。 API 服务器不应直接执行部署任务。 ### Runner 和 Executor 是不同的 ``` Runner = who executes Executor = how execution happens ``` | Runner | Executor | |---|---| | 本地 Runner | Shell 执行器 | | 主机 Runner | SSH 执行器 | | Kubernetes Runner | Kubernetes Job 执行器 | | GitOps Runner | Argo CD 执行器 | | 云 Runner | Webhook / 云适配器 | 这种分离允许 Nivora 支持多种执行环境而无需重写核心编排逻辑。 ### GitOps 是一种部署模式 Nivora 支持 GitOps，但 GitOps 并非产品的全部。 未来的部署模式包括主机部署、原始 Kubernetes YAML、Helm、Kustomize、Argo CD GitOps、基于 Webhook 的交付和特定云提供商的交付。 ### 端口和适配器优先 外部系统必须通过稳定的接口集成： ``` SCMProvider ArtifactProvider CloudProvider Executor WorkflowRuntime SecretProvider NotificationProvider PolicyEngine EventBus ObjectStore ``` 核心用例应依赖于能力，而非具体供应商。 ### 制品应该是不可变的 发布应尽可能指向不可变的制品：镜像摘要、不可变版本、已签名制品和 SBOM 引用。避免使用 `latest` 标签、部署期间的隐式重建以及未跟踪的制品变更。 ### 审计不是可选项 重要的交付操作必须可审计：流水线启动、任务分配、制品选择、批准或拒绝、部署启动、回滚执行、策略违规检测、运行器注册和凭证使用。 审计记录不得包含密钥值。 ### 没有虚假的生产就绪性声明 Nivora 应明确说明当前存在的功能和目标架构。早期阶段不得声称生产就绪、集成完整、持久化调度或尚未实现和验证的安全保证。 ## 端到端交付流程 这是 Nivora 设计所围绕的长期流程。早期阶段仅实现基于 Shell 的 PipelineRun 子集：定义解析、排队运行创建、本地运行器执行、日志、事件、审计记录、重试、超时、取消和时间线查询。 ``` flowchart TB START["Git Push / Manual Trigger / API Trigger"] INGEST["Trigger Ingestion"] PLAN["Create PipelineRun"] SNAPSHOT["Execution Snapshot"] POLICY{"Pre-check Policy Gates"} DENIED["Stop and record policy result"] QUEUE["Queue PipelineRun"] WORKER["Worker Picks Run"] RUNTIME["Build Runtime Plan"] SELECT{"Select Runner"} RUNNER["Runner"] EXECUTOR["Executor"] LOGS["Capture Logs"] STATUS["Persist Status Transitions"] EVENTS["Emit Events"] AUDIT["Write Audit Records"] APPROVAL{"Approval Required?"} DEPLOY["Create DeploymentRun"] MODE{"Deployment Mode"} VERIFY["Verify"] ROLLBACK{"Rollback Needed?"} RB["Rollback"] TIMELINE["Unified Timeline"] START --> INGEST --> PLAN --> SNAPSHOT --> POLICY POLICY -->|Denied| DENIED --> TIMELINE POLICY -->|Allowed| QUEUE --> WORKER --> RUNTIME --> SELECT SELECT --> RUNNER --> EXECUTOR --> LOGS --> STATUS --> EVENTS --> AUDIT AUDIT --> APPROVAL APPROVAL -->|No| DEPLOY APPROVAL -->|Yes| DEPLOY DEPLOY --> MODE --> VERIFY --> ROLLBACK ROLLBACK -->|Yes| RB --> TIMELINE ROLLBACK -->|No| TIMELINE ``` ## PipelineRun 运行时模型 这是 Nivora 正在构建的第一个执行基础。当前实现仅限于最小化的基于 Shell 的 PipelineRun 执行。 ``` sequenceDiagram autonumber participant User as User / CLI / API participant API as API Server participant UC as PipelineRun Usecase participant Repo as Runtime Repositories participant Worker as Worker participant Runner as Runner participant Exec as Executor participant Event as EventBus participant Audit as AuditLog User->>API: POST /api/v1/pipeline-runs API->>UC: CreatePipelineRun(spec) UC->>Repo: Persist PipelineRun, StageRun, JobRun, StepRun UC->>Event: emit pipeline.run.created UC->>Audit: record PipelineRun created UC-->>API: PipelineRun ID Worker->>Repo: Poll queued PipelineRun Worker->>Repo: PipelineRun -> Running Worker->>Event: emit pipeline.run.started Worker->>Audit: record PipelineRun started Worker->>Runner: Assign JobRun Runner->>Exec: Run step Exec-->>Runner: stdout / stderr / exit code Runner->>Repo: Persist LogChunks Runner->>Repo: StepRun / JobRun status Worker->>Repo: PipelineRun final status Worker->>Event: emit completed or failed Worker->>Audit: record lifecycle result User->>API: GET /api/v1/pipeline-runs/{id}/timeline API->>Repo: Query ordered runtime events API-->>User: Timeline ``` ## PipelineRun 状态模型 ``` stateDiagram-v2 [*] --> Pending Pending --> Queued Queued --> Running Running --> Paused Paused --> Running Running --> Succeeded Running --> Failed Running --> Timeout Pending --> Canceled Queued --> Canceled Running --> Canceled Paused --> Canceled Failed --> Retrying Retrying --> Queued Succeeded --> [*] Failed --> [*] Timeout --> [*] Canceled --> [*] ``` ## Runner 和 Executor 模型 ``` flowchart TB CP["Control Plane"] --> RM["Runner Manager"] RM --> LOCAL["Local Runner"] RM --> HOST["Host Runner"] RM --> K8S["Kubernetes Runner"] RM --> GITOPS["GitOps Runner"] RM --> CLOUD["Cloud Runner"] LOCAL --> SHELL["Shell Executor"] HOST --> SSH["SSH Executor"] K8S --> KJOB["Kubernetes Job Executor"] K8S --> HYAML["Helm / YAML Executor"] GITOPS --> ARGO["Argo CD Executor"] CLOUD --> WEBHOOK["Webhook / Cloud Executor"] SHELL --> RESULT["Execution Result"] SSH --> RESULT KJOB --> RESULT HYAML --> RESULT ARGO --> RESULT WEBHOOK --> RESULT RESULT --> CP ``` ## 部署模型 部署执行是目标架构。在当前阶段，它并未作为完整的生产部署引擎实现。 ``` flowchart TB APP["Application"] ENV["Environment"] REL["Release"] DR["DeploymentRun"] TARGET{"ReleaseTarget Type"} APP --> ENV --> REL --> DR --> TARGET TARGET --> HOST["HostTarget"] TARGET --> K8S["KubernetesTarget"] TARGET --> HELM["HelmTarget"] TARGET --> KUSTOMIZE["KustomizeTarget"] TARGET --> ARGO["ArgoCDTarget"] TARGET --> CLOUD["CloudTarget"] TARGET --> WEBHOOK["WebhookTarget"] HOST --> SSH["SSH Executor"] K8S --> YAML["YAML Apply Executor"] HELM --> HEX["Helm Executor"] KUSTOMIZE --> KREN["Kustomize Renderer"] ARGO --> AEX["Argo CD Executor"] CLOUD --> CAD["Cloud Adapter"] WEBHOOK --> WEX["Webhook Executor"] SSH --> VERIFY["Verify"] YAML --> VERIFY HEX --> VERIFY KREN --> VERIFY AEX --> VERIFY CAD --> VERIFY WEX --> VERIFY VERIFY --> RESULT{"Result"} RESULT -->|Healthy| SUCCESS["Deployment Succeeded"] RESULT -->|Unhealthy| ROLLBACK["Rollback Plan"] ``` ## 集成模型 所有外部系统都应通过端口和适配器连接。下面列出的适配器名称是目标集成方向，除非明确记录为已实现。 ``` flowchart LR subgraph CORE["Core Use Cases"] PIPE["Pipeline Usecase"] DEPLOY["Deployment Usecase"] ARTUC["Artifact Usecase"] POLICYUC["Policy Usecase"] RUNUC["Runner Usecase"] end subgraph PORTS["Ports"] SCM["SCMProvider"] ART["ArtifactProvider"] CLOUD["CloudProvider"] EXEC["Executor"] WF["WorkflowRuntime"] SECRET["SecretProvider"] POLICY["PolicyEngine"] BUS["EventBus"] OBJ["ObjectStore"] end subgraph ADAPTERS["Adapters"] SCMAD["GitHub / GitLab / Gitea"] ARTAD["Harbor / Nexus / OCI / S3"] CLOUDAD["AWS / Aliyun / Tencent"] EXECAD["Shell / SSH / K8s Job / Argo CD"] SECRETAD["Built-in / Vault / K8s Secret"] POLICYAD["Built-in / OPA future"] BUSAD["Memory / NATS future"] OBJAD["Local / MinIO / S3"] end CORE --> PORTS SCM --> SCMAD ART --> ARTAD CLOUD --> CLOUDAD EXEC --> EXECAD WF --> BUSAD SECRET --> SECRETAD POLICY --> POLICYAD BUS --> BUSAD OBJ --> OBJAD ``` ## 可观测性与审计模型 ``` flowchart TB RUN["PipelineRun / DeploymentRun"] RUN --> LOGS["Logs"] RUN --> EVENTS["Events"] RUN --> AUDIT["AuditLog"] RUN --> METRICS["Metrics"] RUN --> TRACES["Traces"] LOGS --> TL["Unified Timeline"] EVENTS --> TL AUDIT --> TL METRICS --> DASH["Future Dashboards"] TRACES --> DASH TL --> API["API / CLI / Future Web UI"] DASH --> API ``` ## 核心概念 | 概念 | 含义 | |---|---| | Application | 由 Nivora 管理的产品或服务 | | Environment | 交付上下文，如开发、测试、生产或自定义目标组 | | ReleaseTarget | 具体的部署目标，如主机组、Kubernetes 集群、Argo CD 应用、云目标或 Webhook 目标 | | Pipeline | 阶段、任务和步骤的可复用定义 | | PipelineRun | 一次 Pipeline 的执行 | | StageRun | 一个阶段的执行记录 | | JobRun | 一个任务的执行记录 | | StepRun | 一个步骤的执行记录 | | Release | 版本化的交付意图，通常关联到不可变的制品 | | DeploymentRun | 一次针对目标的发布或部署计划执行 | | Runner | 接收和执行任务的组件 | | Executor | Runner 用于执行工作的机制 | | Artifact | 构建产出，如镜像、jar 包、二进制文件、Chart 包或软件包 | | Artifact Registry | 存储制品的系统 | | Policy | 可以允许、拒绝或要求批准的关口 | | AuditLog | 重要操作的持久化记录 | | Event | 交付生命周期中发出的运行时信号 | | LogChunk | 有序的 stdout、stderr 或系统日志片段 | ## 仓库布局 ``` nivora/ cmd/ nivora-server/ nivora-worker/ nivora-runner/ nivora/ internal/ app/ domain/ usecase/ ports/ adapters/ infra/ api/ api/ openapi/ asyncapi/ proto/ configs/ deployments/ examples/ docs/ scripts/ test/ AGENTS.md PROJECT_CHARTER.md README.md ROADMAP.md CONTRIBUTING.md ``` | 目录 | 用途 | |---|---| | `cmd/` | 仅存放二进制入口点 | | `internal/domain/` | 纯领域概念和状态 | | `internal/usecase/` | 业务编排 | | `internal/ports/` | 外部能力接口 | | `internal/adapters/` | 端口的实现 | | `internal/infra/` | 技术基础设施 | | `internal/api/` | HTTP / gRPC 传输层 | | `api/` | OpenAPI, AsyncAPI, proto 定义 | | `docs/` | 架构、路线图、概念、社区文档 | | `examples/` | 示例流水线和部署规范 | ## 快速开始 ### 前置条件 - Go - Make - Docker (可选，用于本地 compose) - PostgreSQL (可选，取决于运行时模式) ### 构建 ``` make build ``` ### 测试 ``` make test ``` ### 验证 ``` make verify ``` ### 打包 ``` make docker-build make helm-template make helm-lint ``` 打包文档： - [Docker Compose 安装](docs/operations/install-docker-compose.md) - [Kubernetes 安装](docs/operations/install-kubernetes.md) - [配置](docs/operations/configuration.md) - [性能与负载测试](docs/operations/performance.md) - [备份与恢复](docs/operations/backup-restore.md) - [高可用与灾难恢复](docs/operations/ha-disaster-recovery.md) ### 冒烟测试 ``` make smoke-local make smoke-api ``` ### 运行服务器 ``` make run-server ``` ### 运行 Web UI ``` make run-web ``` Web 控制台位于 `web/` 目录下，消费现有的运行时和 `/api/v1/visualization/*` 后端 API。它是第 6.4 阶段的最小化基础，并非完整的前端产品。 ### 健康检查 ``` curl http://localhost:8080/healthz curl http://localhost:8080/readyz curl http://localhost:8080/api/v1/version curl http://localhost:8080/api/v1/system/runtime curl http://localhost:8080/api/v1/system/diagnostics curl http://localhost:8080/metrics ``` `/readyz` 和 `/api/v1/system/diagnostics` 包含针对数据库、对象存储、事件总线、Outbox 恢复和运行器重连状态的轻量级依赖检查。 ### 运行 Worker ``` make run-worker ``` ### 运行 Runner ``` make run-runner ``` ### 命令行界面 ``` go run ./cmd/nivora version go run ./cmd/nivora pipeline run --local examples/pipelines/simple-shell.yaml go run ./cmd/nivora pipeline get
Backend Skeleton"] P05["Phase 0.5
Guardrails"] P06["Phase 0.6
Public Planning"] P1["Phase 1
Minimal Runtime"] P15["Phase 1.5
Durable Runtime Foundation"] P16["Phase 1.6
Runtime DX & Acceptance"] P2["Phase 2.0
YAML Planning Foundation"] P21["Phase 2.1
Kubernetes YAML Runtime"] P22["Phase 2.2
Artifact & Release Binding"] P23["Phase 2.3
GitOps & Argo CD Foundation"] P24["Phase 2.4
Kubernetes Inventory & Rollback Foundation"] P25["Phase 2.5
OCI Digest Resolution"] P26["Phase 2.6
Argo CD Guarded Sync"] P27["Phase 2.7
Release Orchestration"] P30["Phase 3.0
DevSecOps Foundation"] P31["Phase 3.1
Secret & Credential Foundation"] P32["Phase 3.2
Auth & RBAC Foundation"] P33["Phase 3.3
Approvals & Change Windows"] P34["Phase 3.4
Multi-cloud Inventory"] P35["Phase 3.5
Host Deployment Foundation"] P36["Phase 3.6
Durable Runner Runtime"] P3["Future Phase 3
Multi-cloud & DevSecOps"] P40["Phase 4.0
Visualization Backend APIs"] P41["Phase 4.1
Web UI Foundation"] P4["Future Phase 4
Frontend Visualization"] P0 --> P05 --> P06 --> P1 --> P15 --> P16 --> P2 --> P21 --> P22 --> P23 --> P24 --> P25 --> P26 --> P27 --> P30 --> P31 --> P32 --> P33 --> P34 --> P35 --> P36 --> P3 --> P40 --> P41 --> P4 ``` 详情见 [ROADMAP.md](ROADMAP.md) 和 [docs/roadmap/overview.md](docs/roadmap/overview.md)。 ## 贡献图谱 ``` flowchart TB C["Contributor"] C --> G1["Good First Contributions"] C --> G2["Intermediate Contributions"] C --> G3["Advanced Contributions"] C --> G4["Requires RFC"] G1 --> D1["Documentation"] G1 --> D2["Examples"] G1 --> D3["Tests"] G1 --> D4["CLI polish"] G1 --> D5["API schema cleanup"] G2 --> I1["Shell executor improvements"] G2 --> I2["Memory event bus"] G2 --> I3["Local object store"] G2 --> I4["Config validation"] G2 --> I5["Pipeline state tests"] G3 --> A1["PipelineRun state machine"] G3 --> A2["Runner protocol"] G3 --> A3["Log streaming"] G3 --> A4["Persistence"] G3 --> A5["Kubernetes Job executor"] G3 --> A6["YAML renderer"] G3 --> A7["Argo CD adapter"] G3 --> A8["Policy engine"] G4 --> R1["Runner protocol changes"] G4 --> R2["Workflow runtime changes"] G4 --> R3["Database model changes"] G4 --> R4["Cloud provider adapters"] G4 --> R5["Kubernetes / Argo CD integration design"] G4 --> R6["Plugin system changes"] G4 --> R7["Security model changes"] G4 --> R8["Public API breaking changes"] ``` 贡献前请阅读： - [AGENTS.md](AGENTS.md) - [CONTRIBUTING.md](CONTRIBUTING.md) - [PROJECT_CHARTER.md](PROJECT_CHARTER.md) - [docs/README.md](docs/README.md) - [docs/rfcs/README.md](docs/rfcs/README.md) - [docs/architecture/architecture-contract.md](docs/architecture/architecture-contract.md) - [docs/architecture/module-boundaries.md](docs/architecture/module-boundaries.md) - [docs/engineering/testing-policy.md](docs/engineering/testing-policy.md) - [docs/engineering/dependency-policy.md](docs/engineering/dependency-policy.md) 基本期望： - 保持变更范围小 - 遵守架构边界 - 不添加投机性抽象 - 不提交密钥 - 不声称生产就绪 - 架构变更时更新文档 - 公共行为变更时更新 OpenAPI / AsyncAPI - 为行为变更添加测试 ## 贡献者自动化 自动化编码工具和人类贡献者使用相同的仓库规则。规范指导文件是 [AGENTS.md](AGENTS.md)。 特定工具的指导文件应指向 `AGENTS.md`，而不是定义冲突的行为。所有变更必须遵守架构边界、阶段边界、依赖策略、测试策略、安全基线和文档一致性。 ## 验证 运行完整的验证套件： ``` make verify ``` 预期的检查包括： ``` gofmt check go mod tidy check go vet ./... go test ./... go build ./cmd/nivora-server go build ./cmd/nivora-worker go build ./cmd/nivora-runner go build ./cmd/nivora architecture verification secret scanning ``` ## 安全 Nivora 不得提交或暴露密钥。 不要提交令牌、密码、私钥、kubeconfig 文件、云凭证、注册表凭证或看起来真实的伪造凭证。密钥值不得被记录、通过正常 API 返回、存储在审计记录中、嵌入示例或嵌入测试中。 参见 [SECURITY.md](SECURITY.md) 和 [docs/engineering/security-baseline.md](docs/engineering/security-baseline.md)。 第 3.0 阶段增加了本地 DevSecOps 基础： ``` go run ./cmd/nivora security scan artifact registry.example.com/demo/app:latest --local go run ./cmd/nivora security scan manifest examples/security/manifest-privileged-warning.yaml --local go run ./cmd/nivora policy evaluate --subject registry.example.com/demo/app:latest ``` 这些命令使用 noop/假友好的扫描器基础和内置策略关口。Trivy、Cosign、SBOM 生成、OPA、Kyverno、Gatekeeper 和生产安全自动化仍属未来工作。 第 3.1 阶段增加了 SecretRef 和 Credential 元数据： ``` go run ./cmd/nivora secret put --name local-registry-token --value-env NIVORA_TOKEN go run ./cmd/nivora secret provider validate go run ./cmd/nivora credential create --file examples/credentials/registry-credential.yaml --local ``` 密钥值仅在创建和轮换边界时被接受，并且不会通过正常 API 返回。内置提供者仅用于开发。第 7.1 阶段增加了 Vault 和 Kubernetes Secret 适配器基础以及云 KMS 占位符；生产外部密钥存储仍属未来工作。 第 7.0 阶段加固了本地 Auth 和 RBAC 基础： ``` go run ./cmd/nivora auth whoami go run ./cmd/nivora auth permissions go run ./cmd/nivora auth service-account create --name ci --role developer go run ./cmd/nivora auth token create --subject-id
标签：EVTX分析, 子域名突变, 日志审计, 测试用例, 请求拦截