diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..eabea4e --- /dev/null +++ b/.env.example @@ -0,0 +1,13 @@ +# Copy this file to .env and fill values supplied through the approved secret channel. +# Do not commit .env or put actual endpoints, usernames, or passwords in this file. +PLOOP_POSTGRES_HOST= +PLOOP_POSTGRES_PORT=3306 +PLOOP_POSTGRES_DATABASE= +PLOOP_POSTGRES_USER= +PLOOP_POSTGRES_PASSWORD= + +PLOOP_REDIS_HOST= +PLOOP_REDIS_PORT=6379 +PLOOP_REDIS_USERNAME= +PLOOP_REDIS_PASSWORD= +PLOOP_REDIS_INTERNAL_HOST= diff --git a/Makefile b/Makefile index 2dd2835..c800e99 100644 --- a/Makefile +++ b/Makefile @@ -2,11 +2,13 @@ check-docs \ check-backend lint-backend typecheck-backend test-backend \ check-frontend lint-frontend typecheck-frontend build-frontend \ - check ci fmt format-backend format-frontend + check-dev-services check ci fmt format-backend format-frontend UV ?= uv PNPM ?= pnpm +PYTHON ?= python3 PYTHON_VERSION ?= 3.12 +ENV_FILE ?= .env check-docs: python3 scripts/check_docs.py . --exclude scripts/tests/fixtures --exclude frontend/node_modules --exclude frontend/dist --exclude backend/.venv @@ -37,6 +39,9 @@ typecheck-frontend: build-frontend: $(PNPM) --dir frontend build +check-dev-services: + $(PYTHON) scripts/check_dev_services.py --env $(ENV_FILE) + check: check-docs check-backend check-frontend ci: check diff --git a/docs/README.md b/docs/README.md index 837413a..73f9d09 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,13 +30,14 @@ docs/ | [TODO.md](plan/TODO.md) | 当前执行任务、状态、证据、阻塞项与下一步;实施进度唯一台账 | 活跃 | | [v1-frontend-backend-delivery-plan.md](plan/v1-frontend-backend-delivery-plan.md) | 从工程骨架到双语 MultiHop-RAG 首个真实 Run 的实施顺序、契约与验收门 | 已决定 | | [m0a-toolchain-quality-gates-plan.md](plan/m0a-toolchain-quality-gates-plan.md) | M0a 依赖锁定、前端壳、`check-docs` 与统一质量门 | 已完成 | +| [m0a-cloud-dev-services-plan.md](plan/m0a-cloud-dev-services-plan.md) | M0a 受控云中间件环境、显式连通性检查与 Compose v2 前提 | 进行中 | | [document-structure-refactor-plan.md](plan/document-structure-refactor-plan.md) | 当前 V1 契约与历史原型的迁移计划 | 已完成 | | [traceability.md](plan/traceability.md) | 需求 → 架构/决策 → 计划/工作项 → 验证证据的导航 | 活跃 | | [work-items/README.md](plan/work-items/README.md) | 非平凡 AI 实施的最小工作包模板与状态约定 | 活跃 | | [W-M0a-01](plan/work-items/W-M0a-01-monorepo-package-boundary.md) | 已完成的 monorepo 前后端包边界迁移 | 已完成 | | [W-M0a-02](plan/work-items/W-M0a-02-document-current-state-boundaries.md) | 当前 V1 契约与历史 P0 原型的边界收敛 | 已完成 | | [W-M0a-03](plan/work-items/W-M0a-03-toolchain-and-quality-gates.md) | 依赖锁定、前端壳与统一质量门 | 已完成 | -| [W-M0a-04](plan/work-items/W-M0a-04-compose-and-environment-baseline.md) | 环境样例与 PostgreSQL/Redis Compose 基础服务 | 进行中 | +| [W-M0a-04](plan/work-items/W-M0a-04-compose-and-environment-baseline.md) | 云开发中间件环境与 Compose v2 前提 | 进行中 | ## design:架构、契约与运行时 @@ -88,6 +89,7 @@ docs/ |---|---|---| | [quickstart.md](guides/quickstart.md) | 本地示例 RAG 的完整运行方式 | 初版 | | [ai-development-workflow.md](guides/ai-development-workflow.md) | AI 从需求到代码验证的分流、关口与交付流程 | 活跃 | +| [cloud-dev-services.md](guides/cloud-dev-services.md) | 云 PostgreSQL/Redis 开发配置、显式连通性检查与安全边界 | 活跃 | ## 维护约定 diff --git a/docs/decisions/decisions.md b/docs/decisions/decisions.md index 1d4cc97..9241b2a 100644 --- a/docs/decisions/decisions.md +++ b/docs/decisions/decisions.md @@ -149,6 +149,15 @@ - 人工关口:用户结果/验收、架构边界、公开合同、gold/secret、外部依赖、真实 RAG 成本、部署或不可逆操作的变化必须升级为需求或决策并由项目负责人确认;已确认范围内的局部实现和验证由 AI 自主推进。 - 原因:团队会持续用 AI 推动开发。通过小工作项、唯一状态台账和可复现证据,既避免 AI 从模糊愿望跳到大范围改动,也不把低风险实现变成反复审批。 +### D-019:M0a 开发环境直接使用受控云中间件;Docker Compose v2 保留为后续本地编排前提 + +- 日期:2026-08-31 +- 状态:已决定(项目负责人确认) +- 决定:M0a 的开发 PostgreSQL 和 Redis 直接使用项目负责人提供的云服务。连接信息只保存于仓库根 `.env`,该文件必须被 Git 忽略;`.env.example` 只声明字段和非敏感端口,不包含真实主机、用户名或密码。Docker Compose v2 作为本机工具安装并验证,但本工作项不创建或启动本地 PostgreSQL/Redis 容器。 +- 访问与安全:云服务连通性只能由显式 `make check-dev-services` 触发;该命令仅作超时受限的 TCP 检查,不输出凭据、不执行 SQL、不写数据库、不清 Redis。`make check`、CI 和任何真实 RAG 工作流都不得读取 `.env` 或访问这些云服务。 +- 关系:本决定细化当前 M0a 的开发依赖来源,不替代 V1 后续完整平台的 Docker Compose/E2E 目标;待 API、worker 与迁移存在后,再为自包含的本地服务编排建立独立工作项。 +- 原因:开发环境已有受控云中间件,重复启动本地服务会引入不必要的状态分叉;同时保留 Compose v2 工具前提,避免未来完整本地闭环被宿主缺少插件阻塞。 + ## 已收敛的历史问题 ### Q-001:第一轮的系统边界 diff --git a/docs/guides/cloud-dev-services.md b/docs/guides/cloud-dev-services.md new file mode 100644 index 0000000..61da220 --- /dev/null +++ b/docs/guides/cloud-dev-services.md @@ -0,0 +1,44 @@ +# 云开发中间件 + +本指南说明 M0a 的开发 PostgreSQL、Redis 与 Docker Compose v2 工具边界。连接配置来自项目负责人批准的 secret 渠道,不是仓库文档或 CI 的输入。 + +## 前提 + +确认本机 Docker Compose v2 可用: + +```sh +docker compose version +``` + +本工作项不会定义或启动本地 PostgreSQL/Redis 容器。Compose v2 只为后续完整平台的自包含编排和 E2E 保留。 + +## 配置本机环境 + +根目录的 `.env.example` 只给出字段与非敏感端口。将其复制为 `.env`,并只从获批的 secret 渠道填写实际连接信息: + +```sh +cp .env.example .env +``` + +`.env` 被 Git 忽略,严禁提交、粘贴到文档或放入 CI 日志。当前字段使用 `PLOOP_POSTGRES_*` 和 `PLOOP_REDIS_*` 前缀;Redis 的本地开发入口使用 `PLOOP_REDIS_HOST`,可选的内部地址仅存为 `PLOOP_REDIS_INTERNAL_HOST`,不由检查器自动选择。 + +## 显式连通性检查 + +```sh +make check-dev-services +``` + +该命令只对 `.env` 中的 PostgreSQL 与 Redis 主机/端口进行超时受限的 TCP 检查。它不会显示用户名或密码,不会尝试认证、执行 SQL、写数据库、清 Redis 或运行 RAG。 + +如需使用另一份本机配置,可显式指定: + +```sh +make check-dev-services ENV_FILE=/absolute/path/to/local.env +``` + +## CI 与安全边界 + +- `make check`、`make ci` 和 `scripts/ci.sh` 不会读取 `.env`、访问云服务或启动 Docker。 +- 云服务检查仅供经授权的开发者手动运行;它不是 PR/CI gate。 +- 后续 API、worker 或 migration 开始读取这些字段时,必须仍将凭据留在进程环境中,不能写入数据库、artifact、浏览器 DTO、日志或错误文本。 +- 需要自包含的本地 PostgreSQL/Redis Compose 服务时,先创建新的工作项;不得把本机容器与当前云开发数据混用。 diff --git a/docs/plan/TODO.md b/docs/plan/TODO.md index 27324b4..09b134c 100644 --- a/docs/plan/TODO.md +++ b/docs/plan/TODO.md @@ -39,7 +39,7 @@ - 已完成:[W-M0a-01|Monorepo 前后端包边界](work-items/W-M0a-01-monorepo-package-boundary.md);根目录不再保留 Python `src/`、`pyproject.toml` 或 `tests/`。 - 已完成:[W-M0a-02|文档当前态与历史 P0 原型边界收敛](work-items/W-M0a-02-document-current-state-boundaries.md);当前 V1 契约、实施计划与历史 P0 原型已归位,42 份 Markdown 的 196 个仓库内相对链接/锚点审计通过。 - 已完成:[W-M0a-03|工具链与统一质量门](work-items/W-M0a-03-toolchain-and-quality-gates.md);已锁定后端/前端依赖,建立根 `Makefile`、`scripts/ci.sh` 与不联网的 `check-docs`。2026-08-31 的 `make check` 和 `CI_TIER=pr scripts/ci.sh` 均通过。 - - 进行中:[W-M0a-04|环境样例与 Compose 基础服务](work-items/W-M0a-04-compose-and-environment-baseline.md);只建立本地 PostgreSQL/Redis 依赖与不含 secret 的环境样例,不进入数据库 schema、API 或真实 Run。 + - 进行中:[W-M0a-04|云开发中间件环境与 Compose v2 前提](work-items/W-M0a-04-compose-and-environment-baseline.md);已验证 Compose v2 和 PostgreSQL TCP 可达,Redis 域名当前在开发机 DNS 未解析;不创建本地中间件容器,也不进入数据库 schema、API 或真实 Run。 - 验收:干净环境可运行 `backend` 单测、前端 typecheck/lint/build、`make check`;`check-docs` 对正常文档通过,并对故意失效的路径/锚点 fixture 非零退出;根目录不出现任一应用包源码;不创建真实 Run。 - [ ] **M0b|可执行架构与安全检查** `TODO` @@ -82,4 +82,4 @@ ## 当前下一步 -**M0a|工程基线与统一命令入口**。当前叶子工作项是 [W-M0a-04](work-items/W-M0a-04-compose-and-environment-baseline.md):建立环境样例与本地 PostgreSQL/Redis Compose 基础服务;它必须复用现有 `make check`,且不得扩展到数据库 schema、API、DDD 或真实 Run。 +**M0a|工程基线与统一命令入口**。当前叶子工作项是 [W-M0a-04](work-items/W-M0a-04-compose-and-environment-baseline.md):建立云开发中间件环境与 Compose v2 前提;它必须复用现有 `make check`,且不得扩展到数据库 schema、API、DDD 或真实 Run。 diff --git a/docs/plan/m0a-cloud-dev-services-plan.md b/docs/plan/m0a-cloud-dev-services-plan.md new file mode 100644 index 0000000..84b19dd --- /dev/null +++ b/docs/plan/m0a-cloud-dev-services-plan.md @@ -0,0 +1,121 @@ +# M0a 云开发中间件环境实施计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**目标:** 让开发者以未提交的 `.env` 使用已提供的云 PostgreSQL 与 Redis,同时保留 Docker Compose v2 作为后续完整平台 Compose/E2E 的本机工具前提。 + +**架构:** 根 `.env.example` 只声明连接字段和无敏感默认端口;根 `.env` 保存本机实际凭据,始终被 Git 忽略。`scripts/check_dev_services.py` 只在显式 `make check-dev-services` 时读取 `.env` 并执行 TCP 连通性检查,输出 host/port 与状态但绝不输出用户名或密码。当前不创建 `compose.yaml`,因为本工作项不启动本地 PostgreSQL/Redis 容器。 + +**技术栈:** Docker Compose v2、Python 3.12 标准库 `socket`、GNU Make、Git 忽略规则。 + +**依据:** [W-M0a-04](work-items/W-M0a-04-compose-and-environment-baseline.md)、[V1 平台契约](../design/v1-platform-contract.md)、[D-019](../decisions/decisions.md#d-019m0a-开发环境直接使用受控云中间件docker-compose-v2-保留为后续本地编排前提)。 + +## 全局约束 + +- 凭据只能写在根 `.env`;不得出现在 Git、`.env.example`、文档、测试、Make 输出或 CI。 +- `make check`、`make ci` 和 `scripts/ci.sh` 保持离线/只读,不读取 `.env`,不连接云服务,也不启动 Docker。 +- `make check-dev-services` 是唯一的显式云网络检查入口;它只做 TCP 连通性,不执行 SQL、写数据库、清 Redis 或调用 RAG。 +- 本工作项不创建 `compose.yaml`、数据库 schema/migration、FastAPI、worker、DDD、前端业务页面或真实 Run。 +- Docker Compose v2 仅验证版本;本次不以本地容器替代已提供的云 PostgreSQL/Redis。 + +--- + +### Task 1:记录云开发环境决策与修订工作项 + +**文件:** + +- 修改:`docs/decisions/decisions.md` +- 修改:`docs/plan/work-items/W-M0a-04-compose-and-environment-baseline.md` +- 修改:`docs/plan/TODO.md`、`docs/plan/traceability.md`、`docs/README.md` + +- [x] **Step 1: 写明 D-019 与 W-M0a-04 的范围变化** + +将开发依赖明确为受控云 PostgreSQL/Redis;Compose v2 保留为未来完整本地编排的前提,但当前不定义服务容器。 + +- [x] **Step 2: 验证文档链接** + +运行:`make check-docs` +预期:新决策、工作项和追踪链接均通过。 + +### Task 2:以测试驱动建立安全的云服务检查器 + +**文件:** + +- 新建:`scripts/tests/test_check_dev_services.py` +- 新建:`scripts/check_dev_services.py` + +**接口:** `python3 scripts/check_dev_services.py --env ` 读取键值环境文件,要求 PostgreSQL 与 Redis 的 host/port 字段;对每个端点执行超时受限的 TCP 连通性检查,失败返回非零。输出中不得出现用户名或密码。 + +- [x] **Step 1: 写出失败测试** + +覆盖缺少必要字段、可连接本地临时 TCP 服务、无法连接端口,以及错误输出不回显输入中的密码。 + +- [x] **Step 2: 验证 RED** + +运行:`python3 scripts/tests/test_check_dev_services.py` +预期:因检查器不存在而失败。 + +- [x] **Step 3: 实现最小标准库检查器** + +只解析简单 `KEY=VALUE` 行与显式 host/port;不依赖数据库或 Redis Python client,不打印敏感值,不连接实际云服务,除非从命令行显式调用。 + +- [x] **Step 4: 验证 GREEN** + +运行:`python3 scripts/tests/test_check_dev_services.py` +预期:所有 fixture 行为通过。 + +### Task 3:添加环境样例与显式 Make 入口 + +**文件:** + +- 新建:`.env.example` +- 新建(被忽略):`.env` +- 修改:`Makefile`、`.gitignore` +- 修改:`scripts/tests/test_make_targets.py` + +**接口:** `make check-dev-services` 必须显式读取 `ENV_FILE`(默认 `.env`)并调用检查器;`make check` 不依赖该 target。`.env.example` 只有字段名和无敏感端口;`.env` 的实际值永不进入 Git。 + +- [x] **Step 1: 写出失败的 Make 合同测试** + +断言 dry-run 的 `check-dev-services` 使用 `.env` 和 `scripts/check_dev_services.py`,并断言 `make --dry-run check` 不包含该网络目标。 + +- [x] **Step 2: 验证 RED** + +运行:`python3 scripts/tests/test_make_targets.py MakeTargetTest.test_check_dev_services_target_is_available` +预期:目标尚不存在而失败。 + +- [x] **Step 3: 添加 `.env.example`、本机 `.env` 与 Make target** + +实际凭据只写进 Git 忽略的 `.env`;复核 `.env.example`、lockfile 和文档仍会被 Git 正确追踪或忽略。 + +- [x] **Step 4: 验证 GREEN** + +运行:`python3 scripts/tests/test_make_targets.py && make check` +预期:所有本地质量门通过,且未连接云服务。 + +### Task 4:提供安全使用说明并验证显式外部连通性 + +**文件:** + +- 新建:`docs/guides/cloud-dev-services.md` +- 修改:`docs/README.md`、`docs/plan/work-items/W-M0a-04-compose-and-environment-baseline.md` + +- [x] **Step 1: 说明复制样例、显式检查与安全边界** + +文档不出现实际主机、用户名或密码;说明 Docker Compose v2 已作为工具可用、但当前工作项不定义本地容器。 + +- [ ] **Step 2: 验证 Docker Compose v2 与云服务 TCP 连通性(Redis DNS 待外部恢复)** + +运行:`docker compose version` 与 `make check-dev-services`。 +预期:报告 Compose 版本及两项云端点可达性;不打印凭据、不写入数据库/Redis。 + +- [ ] **Step 3: 完整验证、更新状态并提交** + +运行:`python3 scripts/tests/test_check_docs.py && python3 scripts/tests/test_make_targets.py && make check && make check-dev-services`。 +预期:全部返回 0;将实际命令与结果写入 W-M0a-04,推送完成分支供审阅。 + +## 计划自审 + +- 覆盖:Task 1 记录外部依赖决策;Task 2 证明检查器不会泄漏敏感值;Task 3 证明云检查与常规质量门隔离;Task 4 验证本机工具和经授权的云 TCP 连通性。 +- 范围:不包含 local Compose service、schema/migration、应用代码、API、worker、前端、RAG 或任何数据写入。 +- Git:只提交非敏感配置、代码、测试和文档;`.env` 不暂存也不推送。 diff --git a/docs/plan/traceability.md b/docs/plan/traceability.md index 994560b..834b88a 100644 --- a/docs/plan/traceability.md +++ b/docs/plan/traceability.md @@ -4,7 +4,7 @@ | 需求 | 架构 / 决策 | 计划 / 工作项 | 当前验证与状态 | |---|---|---|---| -| [R-001:V1 评测平台](../requirements/R-001-v1-rag-evaluation-platform.md) | [V1 平台契约](../design/v1-platform-contract.md)、[实验契约](../design/experiment-contract.md)、[DDD](../design/ddd-rich-domain-model.md)、[前端架构](../design/frontend-architecture.md)、D-010/D-012/D-015 | [V1 蓝图](v1-frontend-backend-delivery-plan.md) 的 M0–M7;[M0a](TODO.md#实施队列) 的 [W-M0a-03](work-items/W-M0a-03-toolchain-and-quality-gates.md) 已完成,当前 [W-M0a-04](work-items/W-M0a-04-compose-and-environment-baseline.md) | 2026-08-31:后端 P0 回归、前端静态检查、相对链接/锚点 fixture、`make check` 与 PR tier CI 均通过;当前只准备本地基础依赖,平台闭环与真实 benchmark Run 尚未开始 | -| [R-002:AI 开发治理](../requirements/R-002-ai-driven-development-governance.md) | [文档贡献约定](../AGENTS.md)、D-016/D-017/D-018 | [AI 工作流](../guides/ai-development-workflow.md)、[工作项约定](work-items/README.md)、[W-M0a-02](work-items/W-M0a-02-document-current-state-boundaries.md)、[W-M0a-03](work-items/W-M0a-03-toolchain-and-quality-gates.md)、[W-M0a-04](work-items/W-M0a-04-compose-and-environment-baseline.md) | 根 `AGENTS.md`、需求索引、追踪矩阵与工作项模板已建立;2026-08-31 已建立并验证可执行的本地质量门,当前以明确边界推进本地 Compose 基础服务 | +| [R-001:V1 评测平台](../requirements/R-001-v1-rag-evaluation-platform.md) | [V1 平台契约](../design/v1-platform-contract.md)、[实验契约](../design/experiment-contract.md)、[DDD](../design/ddd-rich-domain-model.md)、[前端架构](../design/frontend-architecture.md)、D-010/D-012/D-015/D-019 | [V1 蓝图](v1-frontend-backend-delivery-plan.md) 的 M0–M7;[M0a](TODO.md#实施队列) 的 [W-M0a-03](work-items/W-M0a-03-toolchain-and-quality-gates.md) 已完成,当前 [W-M0a-04](work-items/W-M0a-04-compose-and-environment-baseline.md) | 2026-08-31:本地质量门与 PostgreSQL TCP 检查已通过;Redis 域名尚未在开发机 DNS 解析,故云依赖验收与平台闭环仍未完成 | +| [R-002:AI 开发治理](../requirements/R-002-ai-driven-development-governance.md) | [文档贡献约定](../AGENTS.md)、D-016/D-017/D-018/D-019 | [AI 工作流](../guides/ai-development-workflow.md)、[工作项约定](work-items/README.md)、[W-M0a-02](work-items/W-M0a-02-document-current-state-boundaries.md)、[W-M0a-03](work-items/W-M0a-03-toolchain-and-quality-gates.md)、[W-M0a-04](work-items/W-M0a-04-compose-and-environment-baseline.md) | 根质量门已验证;云连接信息只保存在 Git 忽略的 `.env`,Redis DNS 前置条件仍待外部恢复 | 更新规则:新增或改变需求时先更新 `requirements/`;改变实现机制时更新 `design/` 和必要的 `D-*`;拆分或开始实施时更新工作项与 TODO;交付时在工作项/TODO 写入验证证据并回写本矩阵的状态摘要。 diff --git a/docs/plan/work-items/W-M0a-04-compose-and-environment-baseline.md b/docs/plan/work-items/W-M0a-04-compose-and-environment-baseline.md index 95ffcb5..b2bbf42 100644 --- a/docs/plan/work-items/W-M0a-04-compose-and-environment-baseline.md +++ b/docs/plan/work-items/W-M0a-04-compose-and-environment-baseline.md @@ -1,28 +1,31 @@ -# W-M0a-04:环境样例与 Compose 基础服务 +# W-M0a-04:云开发中间件环境与 Compose v2 前提 状态:`IN PROGRESS` 关联需求:[R-001](../../requirements/R-001-v1-rag-evaluation-platform.md)、[R-002](../../requirements/R-002-ai-driven-development-governance.md) -关联设计/决策:[V1 平台契约](../../design/v1-platform-contract.md)、[工程质量与 CI/CD](../../design/engineering-quality-ci-cd.md)、[D-010](../../decisions/decisions.md#d-010第一轮直接交付平台三段式-cli-成为平台的执行内核)、[D-013](../../decisions/decisions.md#d-013建立-pkg-公共包与可执行的工程质量cicd-门)、[D-017](../../decisions/decisions.md#d-017根目录是-monorepo-编排层应用代码分置-backend-与-frontend) +关联设计/决策:[V1 平台契约](../../design/v1-platform-contract.md)、[工程质量与 CI/CD](../../design/engineering-quality-ci-cd.md)、[D-010](../../decisions/decisions.md#d-010第一轮直接交付平台三段式-cli-成为平台的执行内核)、[D-013](../../decisions/decisions.md#d-013建立-pkg-公共包与可执行的工程质量cicd-门)、[D-017](../../decisions/decisions.md#d-017根目录是-monorepo-编排层应用代码分置-backend-与-frontend)、[D-019](../../decisions/decisions.md#d-019m0a-开发环境直接使用受控云中间件docker-compose-v2-保留为后续本地编排前提) 父计划:M0a ## 目标与非目标 -- 目标:提供不含 secret 的环境变量样例,以及仅启动 PostgreSQL 和 Redis 的可复现 Compose 基础服务,为后续 API/worker 的本地联调准备稳定依赖。 -- 非目标:不建立 FastAPI、worker、领域模型、数据库 schema/migration、业务 API、前端页面、真实 Run、数据导入或真实 RAG;不部署或连接共享/生产基础设施。 +- 目标:提供不含 secret 的环境变量样例和被 Git 忽略的本机云服务配置,使后续 API/worker 能受控地使用项目负责人提供的 PostgreSQL 与 Redis;安装并验证 Docker Compose v2 作为后续本地编排前提。 +- 非目标:不创建本地 PostgreSQL/Redis Compose 服务,不建立 FastAPI、worker、领域模型、数据库 schema/migration、业务 API、前端页面、真实 Run、数据导入或真实 RAG;不部署或连接生产基础设施。 ## 允许影响面 -- 允许路径:根 `compose.yaml`、`.env.example`、`Makefile`、`.gitignore`、`docs/`,以及服务初始化所必需但不含业务数据的根部署配置。 +- 允许路径:根 `.env.example`、被忽略的 `.env`、`Makefile`、`.gitignore`、`scripts/`、`docs/`,以及服务连接检查所必需但不含业务数据的根配置。 - 禁止:`backend/src/ploop/` 的领域/应用/HTTP/worker 实现、`backend` migration、`frontend/src/`、冻结数据/gold、真实凭据、外部数据库、`deploy/` 生产配置。 ## 实施与验收 -1. `compose.yaml` 只定义带具名 volume 与 healthcheck 的本地 PostgreSQL、Redis;镜像版本固定,不包含 PLoop API、worker 或前端容器。 -2. `.env.example` 只包含本地开发的非敏感端口、数据库名/用户与连接变量;默认值与 Compose 一致,真实 `.env` 始终被 Git 忽略。 -3. 根 `Makefile` 提供显式的 Compose 启动、停止、日志与 health/smoke 入口;`make check` 保持只读且绝不启动服务。 -4. 以隔离的本地 Docker Compose 实跑证明两项服务健康;停止后不删除具名 volume,清理数据必须另有显式且经人工确认的命令。 -5. 更新 TODO、追踪矩阵和相关使用说明,保留命令输出、镜像版本与 healthcheck 结果作为完成证据。 +1. Docker Compose v2 在开发机可用并通过版本检查;本项不定义本地 Compose 服务。 +2. `.env.example` 只包含非敏感字段和端口;真实云连接值只位于被 Git 忽略的 `.env`。 +3. 根 `Makefile` 提供显式的云服务 TCP 检查入口;`make check` 保持离线、只读且绝不读取 `.env`。 +4. 以超时受限的 TCP 检查证明两项经授权云端点可达;不执行 SQL、写数据库、清 Redis 或运行 RAG。 +5. 更新 TODO、追踪矩阵和使用说明,保留命令输出、Compose 版本与连通性结果作为完成证据。 ## 完成证据 -- 进行中:工作项已创建,尚未创建 Compose、环境样例或启动任何服务。 +- 2026-08-31:Docker Compose v2 已安装并验证为 5.5.0;本工作项未创建或启动本地 PostgreSQL/Redis 容器。 +- 2026-08-31:已添加被 Git 忽略的本机 `.env`、不含敏感值的 `.env.example`,以及显式 `make check-dev-services` TCP 检查入口。 +- 2026-08-31:`python3 scripts/tests/test_check_dev_services.py` 通过 3 项;`python3 scripts/tests/test_make_targets.py` 通过 7 项;`make check` 通过(48 份 Markdown、228 个相对引用、0 错误)。 +- 进行中:`make check-dev-services` 证明 PostgreSQL 端点可达,但 Redis 的公网和内部域名均在当前开发机 DNS 解析失败。检查器未尝试认证或数据操作;等待可解析的 Redis 地址或网络/DNS 配置后才能完成外部连通性验收。 diff --git a/scripts/check_dev_services.py b/scripts/check_dev_services.py new file mode 100644 index 0000000..f8c03c8 --- /dev/null +++ b/scripts/check_dev_services.py @@ -0,0 +1,110 @@ +"""Explicit, secret-safe TCP reachability checks for development services.""" + +from __future__ import annotations + +import argparse +from dataclasses import dataclass +from pathlib import Path +import socket + + +REQUIRED_ENDPOINT_SETTINGS = { + "postgres": ("PLOOP_POSTGRES_HOST", "PLOOP_POSTGRES_PORT"), + "redis": ("PLOOP_REDIS_HOST", "PLOOP_REDIS_PORT"), +} + + +@dataclass(frozen=True) +class Endpoint: + name: str + host: str + port: int + + +class ConfigurationError(ValueError): + """Raised when the explicitly supplied environment file is incomplete.""" + + +def main() -> int: + arguments = _parser().parse_args() + try: + endpoints = endpoints_from_file(arguments.environment_file) + except ConfigurationError as error: + print(error) + return 1 + + reachable = True + for endpoint in endpoints: + if _is_reachable(endpoint, arguments.timeout): + print(f"{endpoint.name}: reachable {endpoint.host}:{endpoint.port}") + continue + print(f"{endpoint.name}: unreachable {endpoint.host}:{endpoint.port}") + reachable = False + return 0 if reachable else 1 + + +def endpoints_from_file(environment_file: Path) -> tuple[Endpoint, ...]: + settings = _read_environment_file(environment_file) + endpoints: list[Endpoint] = [] + for name, (host_key, port_key) in REQUIRED_ENDPOINT_SETTINGS.items(): + host = _required_setting(settings, host_key) + port = _port_setting(settings, port_key) + endpoints.append(Endpoint(name=name, host=host, port=port)) + return tuple(endpoints) + + +def _parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + description="Check explicit development PostgreSQL and Redis TCP reachability." + ) + parser.add_argument("--env", dest="environment_file", type=Path, required=True) + parser.add_argument("--timeout", type=float, default=3.0) + return parser + + +def _read_environment_file(environment_file: Path) -> dict[str, str]: + try: + lines = environment_file.read_text(encoding="utf-8").splitlines() + except FileNotFoundError as error: + raise ConfigurationError(f"environment file not found: {environment_file}") from error + + settings: dict[str, str] = {} + for line in lines: + stripped = line.strip() + if not stripped or stripped.startswith("#"): + continue + key, separator, value = stripped.partition("=") + if not separator or not key: + raise ConfigurationError("invalid environment file entry") + settings[key] = value + return settings + + +def _required_setting(settings: dict[str, str], key: str) -> str: + value = settings.get(key, "").strip() + if not value: + raise ConfigurationError(f"missing required setting: {key}") + return value + + +def _port_setting(settings: dict[str, str], key: str) -> int: + raw_value = _required_setting(settings, key) + try: + port = int(raw_value) + except ValueError as error: + raise ConfigurationError(f"invalid port setting: {key}") from error + if not 1 <= port <= 65535: + raise ConfigurationError(f"invalid port setting: {key}") + return port + + +def _is_reachable(endpoint: Endpoint, timeout: float) -> bool: + try: + with socket.create_connection((endpoint.host, endpoint.port), timeout=timeout): + return True + except OSError: + return False + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/tests/test_check_dev_services.py b/scripts/tests/test_check_dev_services.py new file mode 100644 index 0000000..ed8a70a --- /dev/null +++ b/scripts/tests/test_check_dev_services.py @@ -0,0 +1,107 @@ +from __future__ import annotations + +from contextlib import contextmanager +from pathlib import Path +import socket +import subprocess +import sys +from tempfile import TemporaryDirectory +from threading import Thread +from typing import Iterator +import unittest + + +REPOSITORY_ROOT = Path(__file__).resolve().parents[2] +CHECK_SERVICES = REPOSITORY_ROOT / "scripts" / "check_dev_services.py" + + +def run_check(environment_file: Path) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [sys.executable, str(CHECK_SERVICES), "--env", str(environment_file)], + cwd=REPOSITORY_ROOT, + text=True, + capture_output=True, + check=False, + ) + + +def write_environment(path: Path, port: int, omitted_key: str | None = None) -> Path: + settings = { + "PLOOP_POSTGRES_HOST": "127.0.0.1", + "PLOOP_POSTGRES_PORT": str(port), + "PLOOP_REDIS_HOST": "127.0.0.1", + "PLOOP_REDIS_PORT": str(port), + } + if omitted_key: + del settings[omitted_key] + environment_file = path / ".env" + environment_file.write_text( + "\n".join(f"{key}={value}" for key, value in settings.items()) + "\n", + encoding="utf-8", + ) + return environment_file + + +@contextmanager +def tcp_server(expected_connections: int) -> Iterator[int]: + listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + listener.bind(("127.0.0.1", 0)) + listener.listen() + listener.settimeout(2) + + def accept_connections() -> None: + for _ in range(expected_connections): + try: + connection, _ = listener.accept() + except (OSError, TimeoutError): + return + connection.close() + + thread = Thread(target=accept_connections, daemon=True) + thread.start() + try: + yield listener.getsockname()[1] + finally: + listener.close() + thread.join(timeout=2) + + +class CheckDevServicesTest(unittest.TestCase): + def test_rejects_missing_required_setting(self) -> None: + with TemporaryDirectory() as temporary_directory: + environment_file = write_environment( + Path(temporary_directory), 1, omitted_key="PLOOP_REDIS_PORT" + ) + result = run_check(environment_file) + + self.assertNotEqual(result.returncode, 0) + self.assertIn("missing required setting: PLOOP_REDIS_PORT", result.stdout) + + def test_accepts_reachable_postgres_and_redis_endpoints(self) -> None: + with TemporaryDirectory() as temporary_directory: + with tcp_server(expected_connections=2) as port: + environment_file = write_environment(Path(temporary_directory), port) + result = run_check(environment_file) + + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("postgres: reachable", result.stdout) + self.assertIn("redis: reachable", result.stdout) + + def test_reports_unreachable_endpoint_without_echoing_password(self) -> None: + secret = "test-only-password-must-not-appear" + with TemporaryDirectory() as temporary_directory: + environment_file = write_environment(Path(temporary_directory), 1) + environment_file.write_text( + environment_file.read_text(encoding="utf-8") + + f"PLOOP_POSTGRES_PASSWORD={secret}\n", + encoding="utf-8", + ) + result = run_check(environment_file) + + self.assertNotEqual(result.returncode, 0) + self.assertIn("postgres: unreachable", result.stdout) + self.assertNotIn(secret, result.stdout + result.stderr) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/tests/test_make_targets.py b/scripts/tests/test_make_targets.py index 2381a44..d67d202 100644 --- a/scripts/tests/test_make_targets.py +++ b/scripts/tests/test_make_targets.py @@ -56,6 +56,32 @@ class MakeTargetTest(unittest.TestCase): self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + def test_check_dev_services_target_is_explicit_and_off_the_default_gate(self) -> None: + development_services = subprocess.run( + ["make", "--dry-run", "check-dev-services"], + cwd=REPOSITORY_ROOT, + text=True, + capture_output=True, + check=False, + ) + default_check = subprocess.run( + ["make", "--dry-run", "check"], + cwd=REPOSITORY_ROOT, + text=True, + capture_output=True, + check=False, + ) + + self.assertEqual( + development_services.returncode, + 0, + development_services.stdout + development_services.stderr, + ) + self.assertIn( + "scripts/check_dev_services.py --env .env", development_services.stdout + ) + self.assertNotIn("check_dev_services.py", default_check.stdout) + def test_check_target_runs_all_m0a_gates(self) -> None: result = run_make("check")