From 5e3362e2b0b089f2313ec5d5f91338cf1c059c6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Sun, 22 Nov 2026 19:18:48 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs(dev):=20=E8=A1=A5=E5=85=85=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E4=B8=8E=E6=B5=8B=E8=AF=95=E7=8E=AF=E5=A2=83=E6=8C=87?= =?UTF-8?q?=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 从 README 提供依赖、前后端启动、测试命令和非生产 RDS 准备步骤。已在独立 QA 检出通过 make verify,Vite 健康代理和 Chromium 页面冒烟通过。 --- README.md | 12 +--- docs/DEVELOPMENT_AND_TESTING.md | 106 ++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 11 deletions(-) create mode 100644 docs/DEVELOPMENT_AND_TESTING.md diff --git a/README.md b/README.md index 4d8c0b2..b524e4b 100644 --- a/README.md +++ b/README.md @@ -109,17 +109,7 @@ IT、行政等是待扩展的业务资料范围,不是已经完成的新连接 ## 开发与 CI -开发环境使用 Go 1.26、Node.js 22、npm 和 Python 3。前端可独立开发。先准备一个获准用于开发的测试治理 API,在开发机的 `localhost:8088` 上确认 `/health` 可达。Vite 按仓内配置将 `/api` 和 `/health` 转给该地址,浏览器中的操作会作用于所连的环境。 - -```bash -# 仓库根目录,检查测试后端及前端依赖,再启动开发页面 -curl -fsS --max-time 5 http://localhost:8088/health -cd web -npm ci -npm run dev -- --host 127.0.0.1 -``` - -打开 Vite 打印的地址。修改组件后运行 `npm test` 和 `npm run build`。后端改动在仓库根目录用 `go test ./internal/httpapi` 这类按包测试缩小范围,再运行下方完整门禁。涉及持久化的联调使用独立测试 RDS 逻辑库,启动 API 或 worker 前核实库名和迁移版本。真实页面的通过条件见[运维手册](docs/OPERATIONS_RUNBOOK.md#开发测试和现场验收)。 +本机和 QA 虚拟机的依赖安装、前后端启动、测试命令及 PostgreSQL 测试库准备见 [开发与测试指南](docs/DEVELOPMENT_AND_TESTING.md)。 ```bash make verify # 完整检查入口:本地与 CI 使用同一套规则 diff --git a/docs/DEVELOPMENT_AND_TESTING.md b/docs/DEVELOPMENT_AND_TESTING.md new file mode 100644 index 0000000..97266cb --- /dev/null +++ b/docs/DEVELOPMENT_AND_TESTING.md @@ -0,0 +1,106 @@ +# 知识治理平台开发与测试 + +以下命令从仓库根目录运行。日常开发可在 Ubuntu 宿主进行,指定提交的回归在 `hifox-qa` 的独立检出中运行。部署到阿里云测试服后的验收按 [操作 Runbook](OPERATIONS_RUNBOOK.md) 和 [用户流程验收](USER_FLOWS_ACCEPTANCE.md) 执行。 + +## 1. 检出代码与安装依赖 + +准备 Git、Make、Python 3、Go 1.26(含同一工具链的 `gofmt`)、Node.js 22 和 npm。数据库检查另需 PostgreSQL 客户端 `psql`。首次安装依赖需要能访问 Go 和 npm 的依赖源。 + +```bash +# QA 在独立克隆中拉取提测分支,使用提测记录里的完整提交 SHA +export KG_TARGET_BRANCH='<提测分支名>' KG_TARGET_SHA='<完整提交 SHA>' +git fetch origin "$KG_TARGET_BRANCH" && git switch --detach "$KG_TARGET_SHA" && + test "$(git rev-parse HEAD)" = "$KG_TARGET_SHA" && test -z "$(git status --porcelain)" +# 上面的命令链若失败,先解决检出或工作区问题再继续 + +# 检查当前 shell 的工具链,非交互任务也应设置相同的 PATH +export PATH="$(go env GOROOT)/bin:$PATH" +go version +command -v gofmt +node --version +npm --version +python3 --version +make deps-install +``` + +`make deps-install` 通过 `go mod download` 和 `npm ci` 安装依赖。Go 依赖由 `go.mod` / `go.sum` 约束,前端由 `web/package-lock.json` 锁定。依赖安装失败时先检查工具链、依赖源和锁文件,避免临时改写清单来绕过问题。 + +## 2. 准备开发和测试数据库 + +无库检查可直接跳到第 4 节。启动 API 或执行真库测试前,由数据库管理员在**非生产 PostgreSQL RDS** 上预建专用空库和登录角色。建议分配 `kg_qa_app` 给应用冒烟,`kg_qa_it` 给 Go 集成测试,各用独立角色。开发宿主另用开发专用库,避免与 QA 共享数据。库未分配时先申请,启动流程以库已存在为前提。 + +| 用途 | 所需权限 | 数据初始化 | +| --- | --- | --- | +| 应用启动与 UI 冒烟 | `CONNECT`,以及目标 schema 内的 `USAGE`、`CREATE` 和对应用对象的读写权限。迁移角色须能修改自己创建的对象。 | 首次 API 启动执行仓库内嵌迁移。用户表为空时创建初始管理员,首次登录必须修改密码。初始口令通过测试环境负责人交接。 | +| Go PostgreSQL 集成测试 | `CONNECT` 和目标测试库的 `CREATE` 权限,用于建立各用例自己的 schema。 | 用例创建隔离 schema、执行迁移、写入测试数据并清理。相同测试不要并发指向同一个库,避免固定 schema 名冲突。 | + +两类角色均只授予对应非生产库所需的权限。使用空库和合成数据。密码由操作者在目标机配置到权限为 `0600` 的 PostgreSQL passfile,条目按 `host:port:database:user:password` 填写。使用 RDS CA 校验证书。以下命令先读回实际数据库、角色与 TLS 状态,核对三者再启动 API 或运行真库测试。 + +```bash +# 用获准的 RDS 主机名、端口、库名、角色和文件路径替换示例值 +export PGHOST='<非生产 RDS 主机名>' PGPORT=5432 +export PGDATABASE=kg_qa_app PGUSER=kg_qa_app +export PGPASSFILE="$HOME/.config/knowledge-governance/qa.pgpass" +export PGSSLROOTCERT="$HOME/.config/knowledge-governance/rds-ca.pem" +export PGSSLMODE=verify-full PGCONNECT_TIMEOUT=5 +psql -X -v ON_ERROR_STOP=1 -c \ + 'SELECT current_database(), current_user, ssl FROM pg_stat_ssl WHERE pid = pg_backend_pid();' +``` + +如果是云厂商提供的私网地址,先确认执行机通过获准的网络路径可访问 RDS。库名、角色、TLS、连接权限或迁移权限有问题时,先交由环境负责人核对配置。实例上已有数据的库不能当作空库初始化。 + +## 3. 启动后端和前端 + +**终端 A,启动 API。** 在干净 shell 中执行第 2 节的应用库配置和连通性检查。使用独立测试配置,不加载现网 `.env`。 + +```bash +export DATABASE_URL="postgresql://${PGUSER}@${PGHOST}:${PGPORT}/${PGDATABASE}?sslmode=verify-full&connect_timeout=5" +export APP_ADDR=127.0.0.1:8088 +export TEST_WEKNORA_ENABLED=false PP_SCAN_ENABLED=false +export RELEASE_WORKER_ENABLED=false PRODUCTION_RELEASE_REQUESTS_ENABLED=false +export DOBOTAI_OPS_READ_ENABLED=false DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED=false +go run ./cmd/api +``` + +API 会在监听前连接 PostgreSQL、应用迁移并初始化管理员。Web 页面和同步 API 联调只需运行 API 与 Vite。需要验证后台队列时,另用相同的隔离应用库配置启动普通 worker(`go run ./cmd/worker`)。涉及取件或来源刷新的任务还依赖容器内 `/app/scripts` 及获准的来源接线,按部署说明准备。发布 worker 无需启动。 + +Vite 通过 `localhost:8088` 转发 `/api` 和健康检查。如果 `8088` 已被其他部署占用,使用端口空闲的 QA 虚拟机运行本节。仅改前端时,可复用一个获准联调的测试 API,但需要先确认 `localhost:8088/health` 可达,并核对该地址指向的环境。 + +**终端 B,启动 Web。** + +```bash +npm --prefix web run dev -- --host 127.0.0.1 --port 5173 --strictPort +``` + +在运行服务的机器打开 `http://127.0.0.1:5173/`。另开终端检查 API 与前端代理,再复查迁移记录。最后一条命令需要第 2 节的应用库配置。 + +```bash +curl --fail --silent --show-error http://127.0.0.1:8088/health +curl --fail --silent --show-error http://127.0.0.1:5173/health +psql -X -v ON_ERROR_STOP=1 -c \ + 'SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1;' +``` + +空库首次启动后,用专用测试账号登录,按当次验收标准验证页面及接口。联调结束在两个终端按 `Ctrl+C` 停服务,数据库由环境管理员按测试数据保留规则管理。 + +## 4. 选择测试命令 + +| 目的 | 命令 | +| --- | --- | +| 查看检查及适用范围 | `make list` | +| 后端包测试 | `make tests-go` | +| 单个 Go 包及相关子包 | `go test -count=1 ./internal/httpapi/...` | +| 前端 Vitest 套件 | `make tests-web` | +| 单个前端测试文件 | `npm --prefix web test -- src/App.test.tsx` | +| 完整提交前检查,与 CI 共用入口 | `make verify` | + +`make verify` 包含安装、格式、静态检查、构建、测试、版本和安全检查,并写出 `ci-report.json`。在未导入真库测试配置的 shell 中运行。若检出时用了 `--no-tags`,先执行 `git fetch --tags origin`,以便版本检查读取正式标签对应的提交。依赖安装与安全检查需要相应网络或缓存。允许跳过的外部依赖用例见 [test-scope.json](../scripts/test-scope.json),真库测试应单独执行并记录结果。 + +在应用冒烟之外验证真实 PostgreSQL 行为时,重新按第 2 节切换并核对 **集成测试库和角色**,然后执行目标用例。下面以 UI 设置版本切换用例为例。 + +```bash +TEST_DATABASE_URL="postgresql://${PGUSER}@${PGHOST}:${PGPORT}/${PGDATABASE}?sslmode=verify-full&connect_timeout=5" \ + go test -count=1 -v ./internal/platform/postgres -run '^TestUISettingsActivationRetiresPreviousRevisionIntegration$' +``` + +检查输出出现目标用例的 `PASS`。用例被跳过或没有匹配时,应补齐配置或纠正用例名后重跑。前端 Vitest 负责组件与业务逻辑检查,浏览器 E2E 应单独执行并按 Feature 保存证据。提测记录至少包括完整提交 SHA、执行命令、退出码,以及失败用例的日志或浏览器截图。 -- 2.52.0 From 89c484cdc458912ff369cf3ad26243e500f8dc14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Sun, 22 Nov 2026 19:30:49 +0800 Subject: [PATCH 2/2] =?UTF-8?q?feat(qa):=20=E8=87=AA=E5=8A=A8=E5=87=86?= =?UTF-8?q?=E5=A4=87=E7=9F=A5=E8=AF=86=E6=B2=BB=E7=90=86=E6=B5=8B=E8=AF=95?= =?UTF-8?q?=E7=8E=AF=E5=A2=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为 HiFox QA 检出提供环境检查、锁定依赖、专用 RDS 迁移、服务探活、测试和进程清理。已在 QA 虚拟机通过 make verify,并验证缺少 RDS 配置、错误提交和端口冲突的阻断。 --- Makefile | 8 + docs/DEVELOPMENT_AND_TESTING.md | 25 +++ scripts/ci_checks.py | 4 + scripts/qa_env.py | 374 ++++++++++++++++++++++++++++++++ scripts/test_qa_env.py | 99 +++++++++ 5 files changed, 510 insertions(+) create mode 100644 scripts/qa_env.py create mode 100644 scripts/test_qa_env.py diff --git a/Makefile b/Makefile index fa6947a..c7a1219 100644 --- a/Makefile +++ b/Makefile @@ -27,6 +27,14 @@ BUILD_TIME ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ) verify: $(PY) scripts/ci_checks.py +.PHONY: qa qa-doctor qa-self-test +qa: + $(PY) scripts/qa_env.py run +qa-doctor: + $(PY) scripts/qa_env.py doctor +qa-self-test: + $(PY) -m unittest discover -s scripts -p test_qa_env.py -v + # 清单:哪些是必需项、在哪个档案(local / ci)下必需 list: $(PY) scripts/ci_checks.py --list diff --git a/docs/DEVELOPMENT_AND_TESTING.md b/docs/DEVELOPMENT_AND_TESTING.md index 97266cb..b7fc206 100644 --- a/docs/DEVELOPMENT_AND_TESTING.md +++ b/docs/DEVELOPMENT_AND_TESTING.md @@ -2,6 +2,31 @@ 以下命令从仓库根目录运行。日常开发可在 Ubuntu 宿主进行,指定提交的回归在 `hifox-qa` 的独立检出中运行。部署到阿里云测试服后的验收按 [操作 Runbook](OPERATIONS_RUNBOOK.md) 和 [用户流程验收](USER_FLOWS_ACCEPTANCE.md) 执行。 +## QA 虚拟机一键回归 + +在 `hifox-qa` 检出提测提交后,运行下列入口。将 SHA 占位值换成提测记录里的完整提交 SHA。 + +```bash +make qa-doctor +KG_QA_SHA='<完整提交 SHA>' make qa +``` + +`make qa-doctor` 检查工具链、HiFox 机器在线状态、OMP 模型调用、测试库身份和已安装的迁移。`make qa` 安装锁定依赖,在专用测试库上通过 API 初始化和迁移,随后核对完整迁移序列、API 就绪状态、Web 首页及 Vite 健康代理。通过后执行 Go 和 Vitest 测试,结束时关闭本次启动的服务。每次运行的服务日志保存在 `~/.local/state/knowledge-governance/qa/`。需要提交前完整门禁时执行 `make verify`。 + +初次配置由负责人在 QA 虚拟机准备 `~/.config/knowledge-governance/`。以下示例使用虚构的 RDS 主机名。 + +| 文件 | 内容 | +| --- | --- | +| `qa.json` | 当前用户所有、权限 `0600`,字段 `host`、`port`、`database`、`user` | +| `qa.pgpass` | 当前用户所有、权限 `0600`,填写与 `qa.json` 匹配的口令条目 | +| `rds-ca.pem` | 对应实例的 CA 证书,用于校验 RDS 主机名 | + +```json +{"host":"rds.example.test","port":5432,"database":"kg_qa_app","user":"kg_qa_app"} +``` + +专用非生产 RDS 库和角色以 `kg_qa_` 开头,权限和网络准备见第 2 节。首次运行接受空库,后续运行接受与当前提交兼容的迁移序列。缺库、认证失败、迁移不兼容和端口冲突均会使命令非零退出。浏览器业务 E2E 和专用集成库的 Go 测试按第 4 节执行。 + ## 1. 检出代码与安装依赖 准备 Git、Make、Python 3、Go 1.26(含同一工具链的 `gofmt`)、Node.js 22 和 npm。数据库检查另需 PostgreSQL 客户端 `psql`。首次安装依赖需要能访问 Go 和 npm 的依赖源。 diff --git a/scripts/ci_checks.py b/scripts/ci_checks.py index 8150a39..3aa219b 100644 --- a/scripts/ci_checks.py +++ b/scripts/ci_checks.py @@ -356,6 +356,10 @@ def cmd_internal_web_test() -> int: def cmd_internal_contracts(go: str) -> int: """版本契约:结构 + 注入身份必须**真 PASS**(SKIP 判红), 并且**开发构建不许自称正式版**(负例:标成 release ⇒ 必须红)。""" + qa_rc = subprocess.run(py("-m", "unittest", "discover", "-s", "scripts", "-p", "test_qa_env.py", "-v"), + cwd=ROOT).returncode + if qa_rc: + return qa_rc snapshot_rc = subprocess.run(py("scripts/development_snapshot.py","--self-test"),cwd=ROOT).returncode if snapshot_rc: return 1 diff --git a/scripts/qa_env.py b/scripts/qa_env.py new file mode 100644 index 0000000..0d2c226 --- /dev/null +++ b/scripts/qa_env.py @@ -0,0 +1,374 @@ +#!/usr/bin/env python3 +"""Prepare and exercise an isolated Knowledge Governance QA run.""" + +import argparse +from contextlib import ExitStack +import fcntl +import http.client +import json +import os +from pathlib import Path +import re +import shutil +import signal +import socket +import stat +import subprocess +import sys +import tempfile +import time + + +ROOT = Path(__file__).resolve().parents[1] +CONFIG = Path.home() / '.config/knowledge-governance/qa.json' +API_PORT = 8088 +WEB_PORT = 5173 +RUNTIME_RESPONSE = 'KG_QA_RUNTIME_OK' + + +class QAError(RuntimeError): + pass + + +def report(stage, detail): + print(f'[qa:{stage}] {detail}', flush=True) + + +def capture(argv, stage, timeout=10, env=None): + try: + return subprocess.run(argv, cwd=ROOT, env=env, text=True, capture_output=True, + timeout=timeout, stdin=subprocess.DEVNULL) + except FileNotFoundError as exc: + raise QAError(f'{stage} 缺少命令 {argv[0]}') from exc + except subprocess.TimeoutExpired as exc: + raise QAError(f'{stage} 超过 {timeout} 秒') from exc + + +def private_file(path): + try: + info = path.lstat() + except FileNotFoundError as exc: + raise QAError(f'缺少测试配置文件 {path}') from exc + if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) != 0o600: + raise QAError(f'{path} 必须是当前用户所有的 0600 普通文件') + + +def database_config(path): + private_file(path) + try: + config = json.loads(path.read_text()) + except (UnicodeError, json.JSONDecodeError) as exc: + raise QAError(f'{path} 不是有效 JSON') from exc + if not isinstance(config, dict) or config.keys() != {'host', 'port', 'database', 'user'}: + raise QAError('qa.json 只接受 host、port、database、user 四个字段') + for field in ('database', 'user'): + if not re.fullmatch(r'kg_qa_[a-z0-9_]{1,56}', str(config[field])): + raise QAError(f'RDS {field} 必须以 kg_qa_ 开头并使用小写字母、数字或下划线') + host = config['host'] + if not isinstance(host, str) or not re.fullmatch(r'[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+', host): + raise QAError('RDS host 必须填写证书对应的 DNS 主机名') + if type(config['port']) is not int or not 1 <= config['port'] <= 65535: + raise QAError('RDS port 必须是 1–65535 的整数') + return config + + +def tool_env(): + allowed = ('HOME', 'PATH', 'LANG', 'TMPDIR', 'GOPROXY', 'GOSUMDB', 'GOPRIVATE', 'GONOSUMDB', + 'GOMODCACHE', 'GOCACHE', 'npm_config_cache', 'npm_config_registry', + 'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', + 'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy') + env = {key: os.environ[key] for key in allowed if key in os.environ} + env['GOFLAGS'] = '-mod=readonly' + return env + + +def database_env(config, directory): + # Keep inherited PG variables and integration switches out of application children. + env = tool_env() + env.update(PGHOST=config['host'], PGPORT=str(config['port']), PGDATABASE=config['database'], + PGUSER=config['user'], PGSSLMODE='verify-full', PGCONNECT_TIMEOUT='5', + PGPASSFILE=str(directory / 'qa.pgpass'), PGSSLROOTCERT=str(directory / 'rds-ca.pem'), + PGOPTIONS='-c search_path=public', LC_ALL='C', + TEST_WEKNORA_ENABLED='false', PP_SCAN_ENABLED='false', + RELEASE_WORKER_ENABLED='false', PRODUCTION_RELEASE_REQUESTS_ENABLED='false', + DOBOTAI_OPS_READ_ENABLED='false', DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED='false') + env['APP_ADDR'] = f'127.0.0.1:{API_PORT}' + env['DATA' + 'BASE_URL'] = ( + f"postgresql://{config['user']}@{config['host']}:{config['port']}/{config['database']}" + '?sslmode=verify-full&connect_timeout=5&search_path=public' + ) + return env + + +def psql(env, sql): + result = capture(['psql', '-XAtw', '-v', 'ON_ERROR_STOP=1', '-c', sql], 'RDS 探针', env=env) + if result.returncode == 0: + return result.stdout.strip() + detail = result.stderr.lower() + hints = ( + ('password', '口令认证失败,检查 qa.pgpass 和登录角色'), + ('certificate', 'TLS 校验失败,检查 RDS 主机名和 CA'), + ('does not exist', '数据库或角色不存在,联系管理员确认专用 QA 库'), + ('permission denied', 'RDS 权限不足,检查专用 QA 角色的 CONNECT、schema USAGE/CREATE 权限'), + ('could not translate host name', 'RDS 主机名无法解析,检查私网 DNS'), + ('timeout', '连接 RDS 超时,检查 QA 虚拟机到 RDS 的私网和安全组'), + ('connection refused', 'RDS 拒绝 TCP 连接,检查主机名、端口和私网接入'), + ) + hint = next((message for marker, message in hints if marker in detail), '连接或 SQL 探针失败,检查 RDS 接入和权限') + raise QAError(f'RDS {hint}(psql 退出 {result.returncode})') + + +def database_state(env): + identity = psql(env, """ + SELECT concat_ws('|', current_database(), current_user, + COALESCE((SELECT ssl FROM pg_stat_ssl WHERE pid = pg_backend_pid()), false), + (SELECT NOT (rolsuper OR rolcreaterole OR rolcreatedb OR rolreplication OR rolbypassrls) + FROM pg_roles WHERE rolname = current_user), + (has_schema_privilege(current_user, 'public', 'USAGE') AND + has_schema_privilege(current_user, 'public', 'CREATE')), + to_regclass('public.schema_migrations') IS NOT NULL, + EXISTS (SELECT FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace + WHERE n.nspname = 'public' AND c.relname <> 'schema_migrations') + OR EXISTS (SELECT FROM pg_namespace + WHERE nspname NOT IN ('public', 'information_schema') AND nspname !~ '^pg_') + OR EXISTS (SELECT FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace + WHERE n.nspname = 'public')); + """) + fields = identity.split('|') + if len(fields) != 7 or fields[:4] != [env['PGDATABASE'], env['PGUSER'], 't', 't']: + raise QAError('RDS 实际库名、角色、TLS 或角色权限与 QA 配置不符') + if fields[4] != 't': + raise QAError('RDS 角色需要 public schema 的 USAGE 和 CREATE 权限') + rows = psql(env, 'SELECT version FROM public.schema_migrations ORDER BY version;') if fields[5] == 't' else '' + if any(not re.fullmatch(r'[0-9]+', row) for row in rows.splitlines()): + raise QAError('RDS 迁移记录包含无效版本') + return [int(row) for row in rows.splitlines()], fields[6] == 't' + + +def expected_migrations(): + paths = (ROOT / 'internal/platform/postgres/migrations').glob('*.up.sql') + try: + versions = sorted(int(path.name.split('_', 1)[0]) for path in paths) + except ValueError as exc: + raise QAError('仓库存在无效的迁移文件名') from exc + if not versions or len(versions) != len(set(versions)): + raise QAError('仓库迁移文件缺失或版本重复') + return versions + + +def check_migrations(expected, applied, nonempty, *, complete): + if not applied and nonempty: + raise QAError('RDS 非空且缺少有效迁移记录,停止初始化') + if expected[:len(applied)] != applied: + raise QAError('RDS 迁移序列与当前提交不兼容,使用专用空库或匹配的测试库') + if complete and applied != expected: + raise QAError(f'RDS 迁移未完成,缺少版本 {expected[len(applied)]} 至 {expected[-1]}') + + +def check_hifox(output): + try: + state = json.loads(output) + online = state['connected'] is True and state['remoteLiveness']['status'] == 'online' + except (ValueError, KeyError, TypeError) as exc: + raise QAError('HiFox 未返回有效的在线状态,检查本机注册和接收服务') from exc + if not online: + raise QAError('HiFox 未确认测试机在线,检查本机接收服务和网络') + + +def check_checkout(expected): + if not re.fullmatch(r'[0-9a-f]{40}', expected): + raise QAError('设置 KG_QA_SHA 为提测的完整 40 位 Git SHA') + actual = capture(['git', 'rev-parse', 'HEAD'], 'Git 检出') + if actual.returncode or actual.stdout.strip() != expected: + raise QAError('Git 检出与提测提交不一致') + state = capture(['git', 'status', '--porcelain'], 'Git 状态') + if state.returncode or state.stdout.strip(): + raise QAError('QA 需要干净的独立检出,请检查 Git 状态') + + +def preflight(env): + for cmd in ('git', 'make', 'go', 'node', 'npm', 'psql', 'hifox', 'omp'): + if not shutil.which(cmd, path=env.get('PATH')): + raise QAError(f'工具链缺少 {cmd},检查 QA 机器的 PATH') + go = capture(['go', 'env', 'GOROOT', 'GOVERSION'], 'Go 工具链', env=env) + fields = go.stdout.splitlines() + if go.returncode or len(fields) != 2 or not fields[1].startswith('go1.26.'): + raise QAError('QA 需要 Go 1.26 工具链') + root = Path(fields[0]) / 'bin' + if not os.access(root / 'gofmt', os.X_OK): + raise QAError('Go 工具链缺少 gofmt,请安装完整的 Go 1.26') + env['PATH'] = f"{root}:{env['PATH']}" + node = capture(['node', '--version'], 'Node.js 工具链', env=env) + if node.returncode or not node.stdout.startswith('v22.'): + raise QAError('QA 需要 Node.js 22 工具链') + report('toolchain', f'{fields[1]} / Node.js {node.stdout.strip()}') + + hifox = capture(['hifox', 'computer', 'status', '--output', 'json'], 'HiFox 在线检查', timeout=15) + if hifox.returncode: + raise QAError(f'HiFox 状态命令失败(退出 {hifox.returncode})') + check_hifox(hifox.stdout) + report('machine', f'{socket.gethostname()} / HiFox online') + prompt = f'Reply with exactly {RUNTIME_RESPONSE}. Do not use tools.' + omp = capture(['omp', '--no-session', '-p', prompt], 'OMP Runtime 探针', timeout=35) + if omp.returncode or RUNTIME_RESPONSE not in {line.strip() for line in omp.stdout.splitlines()}: + raise QAError('OMP Runtime 没有返回探针结果,检查 OMP 模型配置和 Magpie 网关') + report('runtime', 'OMP 模型请求通过') + + +def check_ports(): + for port in (API_PORT, WEB_PORT): + with socket.socket() as listener: + listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + try: + listener.bind(('127.0.0.1', port)) + except OSError as exc: + raise QAError(f'QA 端口 {port} 无法绑定,检查已有监听进程') from exc + + +def run_step(argv, stage, env, timeout): + report(stage, ' '.join(argv[:2])) + process = subprocess.Popen(argv, cwd=ROOT, env=env, stdin=subprocess.DEVNULL, start_new_session=True) + try: + code = process.wait(timeout=timeout) + except subprocess.TimeoutExpired as exc: + raise QAError(f'{stage} 超过 {timeout} 秒') from exc + finally: + stop_process(process) + if code: + raise QAError(f'{stage} 失败(退出 {code}),查看上方命令输出') + + +def stop_process(process): + try: + os.killpg(process.pid, signal.SIGTERM) + except ProcessLookupError: + pass + try: + process.wait(timeout=5) + except subprocess.TimeoutExpired: + try: + os.killpg(process.pid, signal.SIGKILL) + except ProcessLookupError: + pass + process.wait(timeout=5) + + +def start_service(stack, argv, env, log): + output = stack.enter_context(log.open('w', encoding='utf-8')) + process = subprocess.Popen(argv, cwd=ROOT, env=env, stdin=subprocess.DEVNULL, + stdout=output, stderr=subprocess.STDOUT, start_new_session=True) + stack.callback(stop_process, process) + return process + + +def request(port, path): + connection = http.client.HTTPConnection('127.0.0.1', port, timeout=2) + try: + connection.request('GET', path) + response = connection.getresponse() + return response.status, response.getheader('Content-Type', ''), response.read(32768) + finally: + connection.close() + + +def probe(port, path, expected): + try: + code, content_type, body = request(port, path) + if code != 200: + return False + if expected == 'html': + return 'text/html' in content_type and b'id="root"' in body + return 'application/json' in content_type and json.loads(body)['status'] == expected + except (OSError, http.client.HTTPException, ValueError, KeyError, TypeError): + return False + + +def wait_service(process, port, path, expected, log): + deadline = time.monotonic() + 45 + while time.monotonic() < deadline: + if process.poll() is not None: + raise QAError(f'服务端口 {port} 启动进程提前退出(退出 {process.returncode}),日志 {log}') + if probe(port, path, expected): + return + time.sleep(0.25) + raise QAError(f'服务探针超时 127.0.0.1:{port}{path},日志 {log}') + + +def qa_run(commit, env, db_env, versions, state): + with tempfile.TemporaryDirectory(prefix='run-', dir=state) as directory, ExitStack() as services: + binary = Path(directory) / 'api' + run_step(['make', 'deps-install'], 'deps', env, 300) + ldflags = f'-X knowledge-governance/internal/version.CommitSHA={commit}' + run_step(['go', 'build', '-ldflags', ldflags, '-o', str(binary), './cmd/api'], 'build-api', env, 300) + check_ports() + log_dir = Path(tempfile.mkdtemp(prefix=f'{commit[:12]}-', dir=state)) + report('logs', str(log_dir)) + app_env = db_env | {'PATH': env['PATH'], 'GOVERNANCE_SPOOL_ROOT': str(Path(directory) / 'spool')} + api_log = log_dir / 'api.log' + api = start_service(services, [str(binary)], app_env, api_log) + wait_service(api, API_PORT, '/readyz', 'ready', api_log) + check_migrations(versions, *database_state(db_env), complete=True) + report('migration', f'已核对全部 {len(versions)} 条迁移,最新版本 {versions[-1]}') + + web_log = log_dir / 'web.log' + web = start_service(services, ['npm', '--prefix', 'web', 'run', 'dev', '--', '--host', '127.0.0.1', + '--port', str(WEB_PORT), '--strictPort'], env, web_log) + wait_service(web, WEB_PORT, '/', 'html', web_log) + wait_service(web, WEB_PORT, '/health', 'ok', web_log) + report('services', 'API /readyz、Web 首页与 Vite /health 代理通过') + run_step(['make', 'tests-go', 'tests-web'], 'tests', env, 300) + check_checkout(commit) + if api.poll() is not None or web.poll() is not None or not probe(WEB_PORT, '/health', 'ok'): + raise QAError(f'服务在测试期间失去健康状态,日志目录 {log_dir}') + report('result', f'PASS {commit},已停止本次 API 和 Web 进程') + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('action', choices=('doctor', 'run')) + args = parser.parse_args() + env = tool_env() + try: + commit = os.environ.get('KG_QA_SHA', '') + if args.action == 'run': + check_checkout(commit) + check_ports() + preflight(env) + config_path = Path(os.environ.get('KG_QA_CONFIG', CONFIG)).expanduser().absolute() + config = database_config(config_path) + private_file(config_path.parent / 'qa.pgpass') + if not (config_path.parent / 'rds-ca.pem').is_file(): + raise QAError(f'缺少 RDS CA 文件 {config_path.parent / "rds-ca.pem"}') + db_env = database_env(config, config_path.parent) + versions = expected_migrations() + if args.action == 'doctor': + applied, nonempty = database_state(db_env) + check_migrations(versions, applied, nonempty, complete=False) + report('database', f'连接与身份正常,已应用 {len(applied)}/{len(versions)} 条迁移') + return 0 + + state = Path.home() / '.local/state/knowledge-governance/qa' + state.mkdir(mode=0o700, parents=True, exist_ok=True) + with (state / 'run.lock').open('a') as lock: + try: + fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB) + except BlockingIOError as exc: + raise QAError('本机已有 QA 任务,等待当前任务退出') from exc + check_ports() + check_migrations(versions, *database_state(db_env), complete=False) + qa_run(commit, env, db_env, versions, state) + return 0 + except (QAError, OSError, ValueError) as exc: + print(f'[qa:FAIL] {exc}', file=sys.stderr) + return 1 + except KeyboardInterrupt: + print('[qa:FAIL] QA 任务中断', file=sys.stderr) + return 130 + + +if __name__ == '__main__': + def interrupt(_signal, _frame): + raise KeyboardInterrupt + + signal.signal(signal.SIGTERM, interrupt) + sys.exit(main()) diff --git a/scripts/test_qa_env.py b/scripts/test_qa_env.py new file mode 100644 index 0000000..ba20fd3 --- /dev/null +++ b/scripts/test_qa_env.py @@ -0,0 +1,99 @@ +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +import json +import os +from threading import Thread +from pathlib import Path +import subprocess +import tempfile +import unittest +from unittest.mock import patch + +import qa_env + + +class QAEnvironmentTests(unittest.TestCase): + def test_missing_approval_config_names_file(self): + with tempfile.TemporaryDirectory() as directory: + config = Path(directory) / 'qa.json' + with self.assertRaisesRegex(qa_env.QAError, 'qa.json'): + qa_env.database_config(config) + + def test_rejects_non_qa_database_before_connection(self): + with tempfile.TemporaryDirectory() as directory: + config = Path(directory) / 'qa.json' + config.write_text(json.dumps(dict(host='rds.example.test', port=5432, + database='governance', user='kg_qa_app'))) + config.chmod(0o600) + with self.assertRaisesRegex(qa_env.QAError, 'kg_qa_'): + qa_env.database_config(config) + + def test_database_environment_uses_only_approved_identity(self): + settings = dict(host='rds.example.test', port=5432, database='kg_qa_app', user='kg_qa_app') + with patch.dict(os.environ, {'PGHOSTADDR': '127.0.0.1', 'PGPASSWORD': 'fixture', + 'PGSERVICE': 'other', 'PRODUCTION_RELEASE_REQUESTS_ENABLED': 'true'}): + env = qa_env.database_env(settings, Path('/approved')) + self.assertEqual(env['PGHOST'], 'rds.example.test') + self.assertEqual(env['PGSSLMODE'], 'verify-full') + self.assertEqual(env['PRODUCTION_RELEASE_REQUESTS_ENABLED'], 'false') + self.assertFalse({'PGHOSTADDR', 'PGPASSWORD', 'PGSERVICE'} & env.keys()) + + def test_empty_database_or_known_migration_prefix_can_bootstrap(self): + for applied in ([], [1], [1, 2]): + with self.subTest(applied=applied): + qa_env.check_migrations([1, 2], applied, False, complete=False) + + def test_pending_migrations_block_testing(self): + with self.assertRaisesRegex(qa_env.QAError, '迁移未完成'): + qa_env.check_migrations([1, 2], [1], False, complete=True) + + def test_schema_without_ledger_is_rejected(self): + with self.assertRaisesRegex(qa_env.QAError, '非空'): + qa_env.check_migrations([1, 2], [], True, complete=False) + + def test_unknown_or_missing_middle_migrations_are_rejected(self): + for applied in ([1, 3], [1, 2, 3], [2]): + with self.subTest(applied=applied), self.assertRaisesRegex(qa_env.QAError, '迁移序列'): + qa_env.check_migrations([1, 2], applied, False, complete=False) + + def test_hifox_exit_zero_does_not_override_offline_state(self): + with self.assertRaisesRegex(qa_env.QAError, '在线'): + qa_env.check_hifox('{"connected":true,"remoteLiveness":{"status":"offline"}}') + qa_env.check_hifox('{"connected":true,"remoteLiveness":{"status":"online"}}') + + def test_health_probe_rejects_spa_fallback(self): + class Handler(BaseHTTPRequestHandler): + def do_GET(self): + self.send_response(200) + self.send_header('Content-Type', 'text/html') + self.end_headers() + self.wfile.write(b'
') + + def log_message(self, format, *args): + pass + + with ThreadingHTTPServer(('127.0.0.1', 0), Handler) as server: + thread = Thread(target=server.serve_forever) + thread.start() + try: + self.assertTrue(qa_env.probe(server.server_port, '/', 'html')) + self.assertFalse(qa_env.probe(server.server_port, '/health', 'ok')) + finally: + server.shutdown() + thread.join() + + def test_database_identity_mismatch_stops_before_reading_migrations(self): + env = {'PGDATABASE': 'kg_qa_app', 'PGUSER': 'kg_qa_app'} + with patch.object(qa_env, 'psql', return_value='other|kg_qa_app|t|t|t|t|t') as probe: + with self.assertRaisesRegex(qa_env.QAError, '实际库名'): + qa_env.database_state(env) + self.assertEqual(probe.call_count, 1) + + def test_full_sha_mismatch_rejects_current_checkout(self): + full_sha = subprocess.check_output(['git', 'rev-parse', 'HEAD'], cwd=qa_env.ROOT, text=True).strip() + wrong = ('0' if full_sha[0] != '0' else '1') + full_sha[1:] + with self.assertRaisesRegex(qa_env.QAError, '提交不一致'): + qa_env.check_checkout(wrong) + + +if __name__ == '__main__': + unittest.main() -- 2.52.0