在 QA 虚拟机通过 Chromium 复跑和本地提交检查,并验证必填校验失效会触发失败。Gitea 将浏览器回归纳入必需检查。
10 KiB
知识治理平台开发与测试
以下命令从仓库根目录运行。日常开发可在 Ubuntu 宿主进行,指定提交的回归在 hifox-qa 的独立检出中运行。部署到阿里云测试服后的验收按 操作 Runbook 和 用户流程验收 执行。
QA 虚拟机一键回归
在 hifox-qa 检出提测提交后,运行下列入口。将 SHA 占位值换成提测记录里的完整提交 SHA。
make qa-doctor
KG_QA_SHA='<完整提交 SHA>' make qa
make qa-doctor 检查工具链、HiFox 机器在线状态、OMP 模型调用、测试库身份和已安装的迁移。make qa 安装锁定依赖,在专用测试库上通过 API 初始化和迁移,随后核对完整迁移序列、API 就绪状态、Web 首页及 Vite 健康代理。通过后执行 Go、Vitest 和 Chromium 浏览器测试,结束时关闭本次启动的服务。每次运行的服务日志保存在 ~/.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 主机名 |
{"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 的依赖源。
# 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 或运行真库测试。
# 用获准的 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。
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。
npm --prefix web run dev -- --host 127.0.0.1 --port 5173 --strictPort
在运行服务的机器打开 http://127.0.0.1:5173/。另开终端检查 API 与前端代理,再复查迁移记录。最后一条命令需要第 2 节的应用库配置。
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,真库测试应单独执行并记录结果。
在应用冒烟之外验证真实 PostgreSQL 行为时,重新按第 2 节切换并核对 集成测试库和角色,然后执行目标用例。下面以 UI 设置版本切换用例为例。
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。如果用例被跳过或没有匹配,补齐配置或修正用例名后重跑。提测记录包含完整提交 SHA、执行命令、退出码及失败证据。
5. 浏览器回归与提交前检查
浏览器用例、固定数据和独立 Vite 配置位于 web/e2e/,Playwright 版本由前端锁文件固定。第一次运行先执行 make deps-install,再在 QA 机的 web/ 目录用 npm exec -- playwright install chromium 下载对应浏览器。已有浏览器缓存时测试本身可以离线运行。
make tests-e2e
make tests-e2e E2E=scope-rules.spec.ts
python3 scripts/test_changed.py --list
make test-changed
make tests-e2e 在 127.0.0.1:4175 启动夹具页并用 Chromium 检查目录规则。夹具页加载真实 React 编辑器并拦截 API 请求到固定的内存数据。覆盖保存和刷新读回、显示 HTTP 403、展示子目录与兄弟目录各自的继承来源。后端角色权限由 Go 测试覆盖,规则持久化和继承语义由 PostgreSQL 集成测试覆盖。失败截图与 trace 保存在 web/test-results/。
在独立克隆中可运行 git config --local core.hooksPath .githooks 启用仓内提交钩子。钩子先运行可用的全局提交检查,再运行 make test-changed。该入口读暂存差异,能定位时只跑修改的测试文件或 Go 包,遇到生产源码或公共依赖改动时扩大到相关套件。对已有仓库自定义钩子的克隆,应在现有钩子中调用 make test-changed。make verify 继续作为完整提交门禁,Gitea CI 将 Chromium 用例纳入必需检查。本地使用 make tests-e2e 直接运行。