nguyenlpn2015/NovaShop

# NovaShop [](https://github.com/nguyenlpn2015/NovaShop/actions/workflows/ci.yml) [](https://github.com/nguyenlpn2015/NovaShop/actions/workflows/release.yml) [](https://github.com/nguyenlpn2015/NovaShop/releases/latest) [](LICENSE) [](docs/AUDIT.md) 一个生产级的平台工程项目：GitOps 交付、阻止不安全发布的护栏、具备基于操作手册告警的可观测性、基础设施即代码以及灾难恢复 —— 运行在单个 Ubuntu 节点上。 该应用特意设计得很小。**围绕它的平台才是核心主题。** **v1.0.0** · 上线于 [novashop.smartdev.vn](https://novashop.smartdev.vn) · [staging](https://staging.novashop.smartdev.vn) · [dev](https://dev.novashop.smartdev.vn) · [更新日志](CHANGELOG.md) · [路线图](docs/ROADMAP.md) 最后一个徽标是刻意为之的。它运行在单节点上，没有高可用性，这构成了以下所有内容的边界。 ## 当前状态 基于运行中的平台测量得出，而非理想化预期。 | | | |---|---| | Argo CD Applications | **12 / 12** 已同步且健康 | | Prometheus scrape targets | **31 / 31** 启动 | | 告警规则，每条均附带 runbook | **14** 条，全部验证可解析到真实文件 | | 自动化合并前检查 | 跨三个门禁共 **93** 项 | | 架构决策记录 | **15** 条，每条均包含被否决的替代方案 | | 架构视图 | **13** 个，全部采用 Mermaid，且全部可进行 diff 对比 | | Terraform 层 | **7** 层，`fmt` 检查无误，全部通过 validate | | TLS | Let's Encrypt，强制执行 HSTS，续期受到监控 | ## 从这里开始 | 如果你有… | 请阅读 | |---|---| | **5 分钟** | 本页面，然后是[架构概览](docs/architecture/overview.md) | | **一小时，了解全部** | [完整指南](docs/THE_COMPLETE_GUIDE.md) — 集于单一文件的全部平台内容 | | **15 分钟** | 添加[仓库审计](docs/AUDIT.md) — 诚实的评分 | | **你要对我进行面试** | [面试指南](docs/INTERVIEW_GUIDE.md) — 演示 walkthrough 及我预期的提问 | | **你正在准备接受面试** | [docs/interview/](docs/interview/) — 教学指南，107 个问题，备忘录 | | **你想学习这套技术栈** | [NovaShop Academy](docs/academy/) — 基于这些文件编排的 19 个模块；目前已编写 4 个 | | **你想运行它** | [本地开发](docs/operations/local-development.md) | | **你想评判工程水平** | [工程日志](docs/LEARNING_LOG.md) — 发现的缺陷及其发现过程 | ## 快速开始 三条路径，从最短的开始。均无需访问线上平台。 **运行应用** — 约两分钟。 ``` git clone https://github.com/nguyenlpn2015/NovaShop.git && cd NovaShop cp .env.example .env docker compose up --build ``` 前端位于 [localhost:3000](http://localhost:3000)，API 文档位于 [localhost:8000/docs](http://localhost:8000/docs)。这是 Compose，而不是 Kubernetes —— 没有 Argo CD，没有 TLS，也没有可观测性，并且这是 [一项决策而非缺漏](docs/operations/local-development.md#what-local-development-is-not)。 **检查平台是否符合本页面所述** — 约五分钟，无需集群，无需凭据。请参阅下方的[验证任何声明](#verify-any-claim-on-this-page)。 **在你自己的节点上部署** — 约几小时，需一台 Ubuntu 22.04 主机。 [生产环境部署](docs/operations/production-deployment.md) 是完整的流程； [引导流程](docs/architecture/bootstrap-flow.md) 是同样内容的图表展示。 ## 这展示了什么 **强制执行的 GitOps，而非纸上谈兵。** 两个仓库。从期望状态到源的每一个引用都是 40 个字符的 commit SHA，并验证其为 `main` 的祖先节点，且对应注册表中实际存在的镜像。任何不符合要求的内容都会被门禁拦截。 **结构上的发布安全，而非条件上的。** 镜像若未通过扫描就无法进入注册表 —— 构建在本地加载，Trivy 进行扫描，之后工作流才会获取注册表凭据。发布无法与 CI 竞速，因为两者是单一任务图中的节点，而不是两个相互监视的工作流运行。 **针对静默失败设计的可观测性。** 一个 relabel 规则未匹配到任何内容的 scrape job 会渲染、验证、部署并采集不到任何内容 —— 这与健康系统无异。每一个必需的 job 都通过名称进行断言，Traefik 的发现角色被显式断言，并且每一条告警表达式在合并前都基于实时数据进行了评估。 **经过证明的安全，而非假设的安全。** Pod Security Admission 强制执行 `restricted` 策略，并切实拒绝不合规的 pod。容器以非 root 用户运行，配置了 `readOnlyRootFilesystem` 且丢弃了所有 capabilities。默认拒绝的 ingress 在提交前，已在带有控制组的活跃 namespace 中进行了试验。 **将恢复视为一种能力，而非文档。** 证书材料会在 Argo CD 协调之前恢复，否则 cert-manager 会消耗掉每周五次 Let's Encrypt 签发机会中的一次。恢复脚本是经过演练的，而不仅仅是被审查过 —— 这正是我们发现它原本根本无法运行的原因。 ## 架构 ``` flowchart LR DEV["Developer"] -->|"pull request"| GH["GitHub
5 required checks"] GH -->|"merge"| REL["Release
scan, then publish"] REL --> GHCR["GHCR
tagged by commit SHA"] GH -.->|"chart + values
pinned by SHA"| GOPS["NovaShop-GitOps"] GHCR -.->|"image tag"| GOPS GOPS -->|"polled"| ARGO["Argo CD"] ARGO --> APPS["dev · staging · production"] ARGO --> EDGE["Traefik + cert-manager"] ARGO --> OBS["Prometheus · Grafana
Loki · Alertmanager"] TF["Terraform
7 layers"] -.->|"prepares, then hands over"| ARGO NET["Cloudflare → FortiGate"] --> EDGE ``` 十三个视图及其背后的推理：**[docs/architecture/](docs/architecture/)** ## 查看其运行状态 平台是实时的，因此最快的证据是平台本身，而不是它的图片： | | | |---|---| | 生产环境 | [novashop.smartdev.vn](https://novashop.smartdev.vn) — HSTS, Let's Encrypt | | Staging · Development | [staging](https://staging.novashop.smartdev.vn) · [dev](https://dev.novashop.smartdev.vn) — 相同的 chart，不同的 values | | 后端，位于独立主机 | [api.novashop.smartdev.vn/health](https://api.novashop.smartdev.vn/health) · [/live](https://api.novashop.smartdev.vn/live) · [/ready](https://api.novashop.smartdev.vn/ready) | `/live` 返回健康状态，而 `/ready` 报告其依赖项状态，这就是为什么有三个 endpoint 而不是一个 —— [基于 ADR 的推理](docs/architecture/overview.md)。 Argo CD 和 Grafana 未公开暴露 —— 它们持有集群状态且其前方没有 SSO。[截图](docs/screenshots/) 是存放这些控制台截屏的地方，目前存放的是截图程序而非图像本身。 ## 技术栈 | 层级 | 选择 | 原因 | |---|---|---| | Kubernetes | k3s v1.33.13, 单节点, SQLite | [ADR 002](adr/002-kubernetes-distribution.md) | | 交付 | GitOps, 双仓库 | [ADR 003](adr/003-gitops-delivery.md) | | Controller | Argo CD v3.4.4 | [ADR 005](adr/005-gitops-controller.md) | | 打包 | 使用 Helm 安装，使用 Kustomize 进行组合 | [ADR 006](adr/006-helm-and-kustomize.md) | | Edge | Traefik 3.7.4, cert-manager v1.21.0 | [ADR 007](adr/007-ingress-controller.md) | | CI | GitHub Actions, 可复用工作流 | [ADR 008](adr/008-ci-platform.md) | | 指标和日志 | Prometheus, Grafana, Loki, Alloy | [ADR 009](adr/009-observability-stack.md) · [ADR 004](adr/004-log-collection-agent.md) | | Secrets | 通过程序在 Git 之外创建 | [ADR 010](adr/010-secret-management.md) | | IaC | Terraform, 7 层, 非云端 | [ADR 012](adr/012-terraform-scope.md) | | 应用 | FastAPI, Next.js, PostgreSQL 14, Redis | — | ## 刻意缺失的内容 说“不”也是设计的一部分。每一项都有记录在案的原因。 | 未包含的内容 | 原因 | |---|---| | 分布式追踪 | 后端没有业务 endpoint；一个追踪将仅仅是 `GET /ready` 加上两个依赖调用 —— [ADR 011](adr/011-distributed-tracing.md) | | 高可用性 | 单节点。每份文档都如实陈述，而不是暗示冗余。 | | Service mesh, Kyverno, Vault | Pod Security Admission 和 RBAC 已经覆盖了它们在此处能提供的功能 | | 告警路由 | 需要本仓库未持有的凭据以及 on-call 决策 | ## 诚实评估 [docs/AUDIT.md](docs/AUDIT.md) 对七个维度进行了评分，并提供了可证伪每一项的命令。 最薄弱的环节被直言不讳地指出： - **可靠性 3/5** — 9 个后端测试，**0 个前端测试**，无覆盖率测量 - **生产就绪度 2/5** — 单节点，无 HA，告警无处可路由 - **恢复仅停留在文档记录，未经演示。** 每个组件都已测试 —— 前置条件通过，数据库恢复往返 137 行数据且 checksum 一致，被删除的 Service 在 5 秒内完成协调 —— 但完整流程从未在替换节点上运行过。 **RTO 预估为 30-45 分钟，应将其视为未知。** 一个对自身审计报喜不报忧的平台，算不上真正的审计。 ## 仓库布局 ``` adr/ 15 decision records backend/ FastAPI + hand-written Prometheus instrumentation frontend/ Next.js helm/novashop/ The application chart kubernetes/ Platform component values, ingress phases, cert-manager terraform/ 7 layers, non-cloud IaC argocd/ Bootstrap manifests and the pinned Argo CD digest scripts/ Bootstrap, validation gates, backup, restore, recovery runbooks/ An index; the runbooks live beside the alerts they serve docs/ 93 documents — architecture, operations, runbooks, audits, academy diagrams/ Subsystem diagrams predating docs/architecture/ .github/ CI, release, validation workflow, rulesets as JSON ``` 期望状态位于第二个仓库中： [NovaShop-GitOps](https://github.com/nguyenlpn2015/NovaShop-GitOps)。 ## 验证本页面的任何声明 ``` git clone https://github.com/nguyenlpn2015/NovaShop.git git clone https://github.com/nguyenlpn2015/NovaShop-GitOps.git cd NovaShop bash scripts/validate-platform.sh --gitops-dir ../NovaShop-GitOps # 38 checks bash scripts/validate-gitops-revisions.sh --gitops-dir ../NovaShop-GitOps # 30 checks bash scripts/validate-observability.sh --gitops-dir ../NovaShop-GitOps # 25 checks docker run --rm -v "$PWD:/repo" -w /repo hashicorp/terraform:1.9.8 \ fmt -check -recursive terraform ``` 以上三项无需集群且无需凭据即可运行。 ## 文档 [docs/README.md](docs/README.md) 是索引。最有用的入口点： - [架构](docs/architecture/) — 13 个视图 - [运维](docs/operations/) — 部署、故障排除、升级、备份、可观测性 - [Runbooks](docs/observability/runbooks/) — 每条告警一个，共 14 个 - [ADRs](adr/) — 为什么选择每项技术，以及落选的是什么 - [审计](docs/AUDIT.md) · [Terraform 审计](docs/TERRAFORM_AUDIT.md) - [路线图](docs/ROADMAP.md) — 已交付、下一步计划以及刻意排除在外的内容 - [发布检查清单](docs/RELEASE_CHECKLIST.md) — 打标签前验证的内容 ## 贡献 欢迎提交 Pull request，包括那些反对此处所做决策的 Pull request。 - **[CONTRIBUTING.md](CONTRIBUTING.md)** — 工作流、必需的检查以及从何开始 - 这三个门禁只需几分钟即可运行完毕，无需集群和凭据；它们是了解该平台认为何为正确准则的最快途径 - 目前最有用的贡献：指出有误的文档、前端测试（目前为零），或者十五个尚未编写的 [Academy](docs/academy/) 模块之一 - 通过 [安全公告](https://github.com/nguyenlpn2015/NovaShop/security/advisories/new) 私下报告漏洞，切勿使用公开 issue —— [SECURITY.md](SECURITY.md) [MIT](LICENSE) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)

标签：API集成, GitOps, 可观测性, 平台工程, 开源框架, 持续集成, 搜索引擎查询, 测试用例, 自定义请求头, 请求拦截