Compare commits

..

1 Commits

Author SHA1 Message Date
狐友 GXXP & Miku ad02e8bb9c feat(settings): 页面录入测试/生产 WeKnora 连接与密钥并收敛可达性判定
build / build (push) Successful in 1m43s
连接(地址 + 写-only 密钥)从文件引用搬进治理库:AES-GCM 密文 + 独立 0600 主密钥,
页面与接口只回显尾 4 位;测试连接真实列库并区分 地址不可达/密钥无效/无权限/成功,
换地址或换密钥必须测通才能保存(迁移 000083)。

可达性判定收敛为 weknora.HTTPAllowed,客户端与监控探活共用;新增
WEKNORA_ALLOW_PRIVATE_HTTP 只放行 RFC1918/回环/链路本地。生产绑定只保留下拉,
保存后回报冻结/未冻结条数,已冻结目标不被改写。
2026-11-22 15:18:34 +08:00
45 changed files with 2809 additions and 305 deletions
+6
View File
@@ -43,6 +43,12 @@ PRODUCTION_RELEASE_REQUESTS_ENABLED=false
PRODUCTION_WEKNORA_BASE_URL=
PRODUCTION_WEKNORA_API_KEY_FILE=
PRODUCTION_WEKNORA_ALLOW_DOCKER_HTTP=false
# 连接(地址 + 写-only 密钥)密文存治理库;主密钥是独立的 0600 32 字节文件。
WEKNORA_BINDING_MASTER_KEY_FILE=
# 同网段 http(生产 18093 反代)放行:只接受 RFC1918/回环/链路本地,公网 http 仍拒绝。
WEKNORA_ALLOW_PRIVATE_HTTP=false
# 可信 TLS 反代之后录入密钥(X-Forwarded-Proto=https + 同源)。
WEKNORA_BINDING_TRUST_TLS_PROXY=false
PP_SCAN_ENABLED=false
PP_SCAN_HOST_DATA_ROOT=/home/zheromiku/dobot-portal-sync/data
PP_SCAN_CONTAINER_DATA_ROOT=/home/zheromiku/dobot-portal-sync/data
+11
View File
@@ -33,11 +33,22 @@
worker 完全相同的 `LIBRARY_*` 配置与维护协调器,绝不触碰封存源;任一步失败都
保持维护并写报告,不伪造通过。
- `internal/librarystack`:目标/预备份/维护栈的唯一装配点(同步、恢复、基线、演练共用)。
- **测试/生产 WeKnora 连接可在页面上配置**(`GET /api/v1/weknora-connections`、
`POST /api/v1/weknora-connections/{environment}/test`、
`PUT /api/v1/weknora-connections/{environment}`):API Key 以 AES-GCM 密文存治理库
(主密钥为独立 0600 文件),页面与接口只回显尾 4 位;「测试连接」真实请求该实例的
知识库列表并区分地址不可达 / 密钥无效(401) / 无权限(403) / 成功(库数量),换地址或
换密钥必须测通才能保存。密钥存储抽成 `internal/sealedsecret`,QA-AI 侧改为复用同一实现。
### Changed
- 基线作业的"已有生效版本"判定改为三种状态(own / foreign / none),并在
阶段里写明是否走"只收尾"续作。
- WeKnora 的可达性判定收敛为一份(`weknora.HTTPAllowed`):客户端与监控探活共用,
不再出现「卡片可达、列库失败」。新增 `WEKNORA_ALLOW_PRIVATE_HTTP` 只放行
RFC1918/回环/链路本地 http,公网 http 仍拒绝;生产 `18093` 同网段反代因此可用。
- 「生产知识库绑定」只保留下拉选择,删除手输 ID 的降级入口;保存后回报
「已冻结目标 / 仍可改指向」条数,已冻结的执行目标不被改写。
## 开发快照(首次发布入口:同步授权、目标权威基线与维护能力)
+12 -2
View File
@@ -100,7 +100,7 @@ IT、行政等是待扩展的业务资料范围,不是已经完成的新连接
## 配置与安全边界
- 网页服务地址用于控制台探活与配置核验;真正的发布目标由受限发布运行时配置决定,两者不能混为一谈。
- 密钥通过文件或 secret 引用提供,不写入 Git、网页响应或日志。示例配置不是真实凭据。
- 测试/生产 WeKnora 的地址与 API Key 可在「系统设置 → 测试/生产知识库绑定」里录入:密钥以 AES-GCM 密文存治理库(主密钥是独立 0600 文件),页面与接口只回显尾 4 位,日志、审计与响应都不出现明文。部署期仍可用文件引用作为兜底;示例配置不是真实凭据。
- 生产请求与 Release Worker 默认关闭;启用状态必须现场确认。测试处理成功、自动审核或批次锁定都不能绕过生产门禁。
- 来源扫描与取件不应改写原始业务资料;目标知识库的发布、移除和回滚属于独立受控动作。
- 发布与恢复前必须按目标环境准备备份,并核验可恢复性。
@@ -109,7 +109,17 @@ IT、行政等是待扩展的业务资料范围,不是已经完成的新连接
## 开发与 CI
本机和 QA 虚拟机的依赖安装、前后端启动、测试命令及 PostgreSQL 测试库准备见 [开发与测试指南](docs/DEVELOPMENT_AND_TESTING.md)。
开发环境使用 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#开发测试和现场验收)。
```bash
make verify # 完整检查入口:本地与 CI 使用同一套规则
+162
View File
@@ -3387,6 +3387,117 @@
}
}
},
"/api/v1/weknora-connections": {
"get": {
"tags": [
"Settings"
],
"operationId": "listWeKnoraConnections",
"summary": "读取测试/生产 WeKnora 连接状态(只回显密钥尾4位)",
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/api/v1/weknora-connections/{environment}/test": {
"post": {
"tags": [
"Settings"
],
"operationId": "testWeKnoraConnection",
"summary": "用真实列库区分地址不可达/密钥无效/无权限/成功(管理员)",
"parameters": [
{
"name": "environment",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"test",
"production"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WeKnoraConnectionTest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/api/v1/weknora-connections/{environment}": {
"put": {
"tags": [
"Settings"
],
"operationId": "saveWeKnoraConnection",
"summary": "保存测通的连接;密钥密文入库,响应只回尾4位(管理员)",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
},
{
"name": "environment",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"test",
"production"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WeKnoraConnectionSave"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Envelope"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/api/v1/ui-settings": {
"get": {
"tags": [
@@ -5676,6 +5787,57 @@
}
},
"schemas": {
"WeKnoraConnectionTest": {
"type": "object",
"additionalProperties": false,
"properties": {
"endpoint": {
"type": "string"
},
"api_key": {
"type": "string",
"writeOnly": true
},
"key_action": {
"type": "string",
"enum": [
"keep",
"replace",
"clear"
]
}
}
},
"WeKnoraConnectionSave": {
"type": "object",
"additionalProperties": false,
"required": [
"endpoint",
"key_action",
"base_revision"
],
"properties": {
"endpoint": {
"type": "string"
},
"api_key": {
"type": "string",
"writeOnly": true
},
"key_action": {
"type": "string",
"enum": [
"keep",
"replace",
"clear"
]
},
"base_revision": {
"type": "integer",
"minimum": 0
}
}
},
"QAReportedHistoricalRate": {
"type": "object",
"additionalProperties": false,
+50 -8
View File
@@ -26,6 +26,7 @@ import (
"knowledge-governance/internal/qawemail"
"knowledge-governance/internal/serviceverify"
"knowledge-governance/internal/version"
"knowledge-governance/internal/weknoraconn"
)
// dingtalkSourceLister 是「系统设置 → 数据源配置」的数据源发现实现:只读列举钉钉知识库与
@@ -129,17 +130,26 @@ func run(ctx context.Context, getenv func(string) string) error {
}
return settings.TestWeKnoraBaseURL
}
monitorProvider, err := monitoring.NewRealProvider(monitoring.RealProviderConfig{DB: pool, WeKnoraBaseURL: config.TestWeKnoraBaseURL, TestWeKnoraResolver: testEndpointResolver, ProductionWeKnoraBaseURL: config.ProductionWeKnoraBaseURL, ProductionWeKnoraResolver: productionEndpointResolver, MinerUBaseURL: config.MinerUBaseURL, WeKnoraReadiness: weknoraReadiness, WorkerStaleAfter: config.WorkerLivenessStaleAfter})
// 「连接」是页面可配的一等状态:地址 + 写-only 密钥密文入库,其他功能只从
// 这里解析,不再各自读文件凭据,避免出现两个来源。
connectionService := weknoraconn.New(postgresstore.NewStore(pool), weknoraconn.Config{
MasterKeyFile: config.WeKnoraBindingMasterKeyFile,
AllowPrivateHTTP: config.WeKnoraAllowPrivateHTTP,
})
monitorProvider, err := monitoring.NewRealProvider(monitoring.RealProviderConfig{DB: pool, WeKnoraBaseURL: config.TestWeKnoraBaseURL, TestWeKnoraResolver: testEndpointResolver, ProductionWeKnoraBaseURL: config.ProductionWeKnoraBaseURL, ProductionWeKnoraResolver: productionEndpointResolver, MinerUBaseURL: config.MinerUBaseURL, WeKnoraReadiness: weknoraReadiness, WorkerStaleAfter: config.WorkerLivenessStaleAfter, AllowPrivateHTTP: config.WeKnoraAllowPrivateHTTP})
if err != nil {
return err
}
serviceTargetVerifier := serviceverify.New(serviceverify.Config{
TestAPIKeyFile: config.TestWeKnoraAPIKeyFile,
ProductionAPIKeyFile: config.ProductionWeKnoraAPIKeyFile,
TestBaseURLFallback: config.TestWeKnoraBaseURL,
ProductionBaseURLFallback: config.ProductionWeKnoraBaseURL,
TestAllowDockerHTTP: config.TestWeKnoraAllowDockerHTTP,
ProductionAllowDockerHTTP: config.ProductionWeKnoraAllowDockerHTTP,
TestAPIKeyFile: config.TestWeKnoraAPIKeyFile,
ProductionAPIKeyFile: config.ProductionWeKnoraAPIKeyFile,
TestBaseURLFallback: config.TestWeKnoraBaseURL,
ProductionBaseURLFallback: config.ProductionWeKnoraBaseURL,
TestAllowDockerHTTP: config.TestWeKnoraAllowDockerHTTP,
ProductionAllowDockerHTTP: config.ProductionWeKnoraAllowDockerHTTP,
ProductionAllowPrivateHTTP: config.WeKnoraAllowPrivateHTTP,
TestAllowPrivateHTTP: config.WeKnoraAllowPrivateHTTP,
ConnectionResolver: connectionService,
})
// 「版本记录」:只读查询面在 API 侧接线;真正的抓取在 worker 侧(未配置来源即未接线)。
versionHistoryStore, versionHistoryRepo := httpapi.VersionHistoryStore(nil), ""
@@ -185,10 +195,14 @@ func run(ctx context.Context, getenv func(string) string) error {
InternalRoutingKnowledgeBaseID: config.InternalRoutingKnowledgeBaseID,
ExternalRoutingKnowledgeBaseID: config.ExternalRoutingKnowledgeBaseID,
RoutingBindings: postgresstore.NewStore(pool),
KnowledgeBases: knowledgeBaseLister,
KnowledgeBases: connectionAwareBases{service: connectionService, fallback: knowledgeBaseLister, allowPrivate: config.WeKnoraAllowPrivateHTTP},
ProductionBindings: postgresstore.NewStore(pool),
ProductionKnowledgeBases: serviceTargetVerifier,
ProductionWeKnoraBaseURL: config.ProductionWeKnoraBaseURL,
WeKnoraConnections: connectionService,
WeKnoraAllowPrivateHTTP: config.WeKnoraAllowPrivateHTTP,
WeKnoraTrustTLSProxy: config.WeKnoraBindingTrustTLSProxy,
WeKnoraConnectionResolver: connectionService,
ServiceTargetVerifier: serviceTargetVerifier,
ProductionReleaseRequestsEnabled: config.ProductionReleaseRequestsEnabled,
TestAutoReviewPolicy: config.TestAutoReviewPolicy,
@@ -255,3 +269,31 @@ func run(ctx context.Context, getenv func(string) string) error {
return server.Shutdown(shutdownCtx)
}
}
// connectionAwareBases prefers the admin-managed connection over the bootstrap
// env credential, so 「测试知识库绑定」 lists the very instance the connection card
// probes — one source, not two.
type connectionAwareBases struct {
service *weknoraconn.Service
fallback httpapi.KnowledgeBaseLister
allowPrivate bool
}
func (lister connectionAwareBases) ListKnowledgeBases(ctx context.Context) ([]weknora.KnowledgeBase, error) {
if endpoint, apiKey, ok := lister.service.Resolve(ctx, weknoraconn.EnvironmentTest); ok {
client, err := weknora.NewClient(weknora.ClientConfig{
BaseURL: endpoint,
APIKey: apiKey,
Timeout: 10 * time.Second,
AllowPrivateHTTP: lister.allowPrivate,
})
if err != nil {
return nil, err
}
return client.ListKnowledgeBases(ctx)
}
if lister.fallback == nil {
return nil, errors.New("测试 WeKnora 未配置:请先在系统设置里录入连接")
}
return lister.fallback.ListKnowledgeBases(ctx)
}
+6
View File
@@ -70,6 +70,12 @@ services:
PRODUCTION_WEKNORA_BASE_URL: "${PRODUCTION_WEKNORA_BASE_URL:-}"
PRODUCTION_WEKNORA_API_KEY_FILE: "${PRODUCTION_WEKNORA_API_KEY_FILE:-}"
PRODUCTION_WEKNORA_ALLOW_DOCKER_HTTP: "${PRODUCTION_WEKNORA_ALLOW_DOCKER_HTTP:-false}"
# 连接(地址 + 写-only 密钥)密文存治理库:主密钥是独立的 0600 文件。
# 生产 18093 是同网段 http 反代,因此需要显式放行私网 http(只放行
# RFC1918/回环/链路本地,公网 http 仍被拒绝)。
WEKNORA_BINDING_MASTER_KEY_FILE: "${WEKNORA_BINDING_MASTER_KEY_FILE:-}"
WEKNORA_ALLOW_PRIVATE_HTTP: "${WEKNORA_ALLOW_PRIVATE_HTTP:-false}"
WEKNORA_BINDING_TRUST_TLS_PROXY: "${WEKNORA_BINDING_TRUST_TLS_PROXY:-false}"
# 数据源发现(系统设置 → 数据源配置):api 用 dws 只读列举钉钉知识库与钉盘空间。
DWS_BIN: /usr/local/bin/dws
DWS_CONFIG_DIR: /data/dws
-106
View File
@@ -1,106 +0,0 @@
# 知识治理平台开发与测试
以下命令从仓库根目录运行。日常开发可在 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、执行命令、退出码,以及失败用例的日志或浏览器截图。
+3 -2
View File
@@ -160,8 +160,9 @@ bash scripts/target_kb_snapshot.sh # 默认云内执行;PG 8 表 +
| 分区 | 谁 | 现在要管什么 |
|---|---|---|
| 服务配置 | 管理员 | 测试地址 / 生产地址 / 生产 ID / 知识库 ID(保存时真探活,无效才拒) |
| 测试知识库绑定 | 管理员 | 标注往哪个测试库路由(对内 ≠ 对外) |
| 生产知识库绑定 | 管理员 | 源库 → 目标库映射(发布写哪个生产库) |
| 测试知识库绑定 | 管理员 | 顶部连接卡:测试地址 + API Key(测试连接 → 保存;只回显尾4位);下方标注往哪个测试库路由(对内 ≠ 对外) |
| 生产连接 | 管理员 | 生产地址填同网段反代 `http://172.29.151.11:18093`(需要 `WEKNORA_ALLOW_PRIVATE_HTTP=true`),密钥录入后只回显尾4位;停止 `ssh -L 18092` 隧道后仍可用 |
| 生产知识库绑定 | 管理员 | 源库 → 目标库映射(发布写哪个生产库);选项来自生产实例真实库,禁止手填 ID;保存后回报「已冻结 / 仍可改指向」条数 |
| **存储与备份** **【新】** | 管理员 | **定时时间 + 储存天数**(+每月归档、启用开关)→ `保存并下发到主机`;另有 `重新下发当前设置`、`立即备份一次`;页面显示主机上**实际生效**的计划、cron 条目、最近一次结果与"已一致/待下发" |
| 刷新策略 | 文档工程师 | 文档/资源刷新间隔、停滞判定、finalizing 时长(版本化 + 原子切换) |
| 成员与角色 | 管理员 | 成员与 viewer/engineer/admin |
+6
View File
@@ -260,6 +260,12 @@
- 规则:只配四项(测试地址、生产地址、生产 ID、知识库 ID);**保存时真探测**,无效才拒;凭据只写不读
- 状态:✅(见 `P41/P42` 与 `ui_settings_*` 测试)
### D1b 连接(地址 + API Key,测试 / 生产各一张)
- 入口:**系统设置 → 测试知识库绑定 / 生产知识库绑定** 分区顶部的连接卡(管理员)
- 步骤:填地址 → 粘贴 API Key(密码框)→ **测试连接** → 成功后才可 **保存连接**;换地址或换密钥必须重新测通
- 期望:密钥密文入库、页面只显示「已配置 · 尾4位」;四态文案分别是 地址不可达 / 密钥无效 / 密钥无权限读取知识库列表 / 可达(读到 N 个知识库);保存不触发任何同步或发布
- 状态:✅(`internal/weknoraconn` 单测 + `internal/httpapi/weknora_connections_test.go`;迁移 000083)
### D2 测试知识库绑定(对内 / 对外)
- 入口:**系统设置 → 测试知识库绑定** → 选库 → 保存绑定
- 期望:保存立即生效并重排"还没上传"的待入库项;对内 ≠ 对外
+43 -22
View File
@@ -31,28 +31,33 @@ type Config struct {
ProductionWeKnoraBaseURL string
ProductionWeKnoraAPIKeyFile string
ProductionWeKnoraAllowDockerHTTP bool
PPScanEnabled bool
PPScanAllowedRoot string
PPScanLedgerPath string
PPScanManifestPath string
TestWeKnoraEnabled bool
TestWeKnoraAllowDockerHTTP bool
TestWeKnoraBaseURL string
MinerUBaseURL string
TestWeKnoraKBID string
InternalRoutingKnowledgeBaseID string
ExternalRoutingKnowledgeBaseID string
TestWeKnoraAPIKeyFile string
GovernanceSpoolRoot string
IngestionSpoolRoot string
ArtifactFetchMaxBytes int64
WorkerLivenessStaleAfter time.Duration
TestWeKnoraHTTPTimeout time.Duration
TestWeKnoraPollInitial time.Duration
TestWeKnoraPollMax time.Duration
TestWeKnoraStalledAfter time.Duration
TestWeKnoraMaxUploadBytes int64
TestAcceptancePolicyVersion string
// 连接(地址 + 写-only 密钥)密文存治理库;主密钥是独立的 0600 文件。
WeKnoraBindingMasterKeyFile string
// 允许同网段 http(生产 18093 反代)与可信 TLS 反代后录入密钥。
WeKnoraAllowPrivateHTTP bool
WeKnoraBindingTrustTLSProxy bool
PPScanEnabled bool
PPScanAllowedRoot string
PPScanLedgerPath string
PPScanManifestPath string
TestWeKnoraEnabled bool
TestWeKnoraAllowDockerHTTP bool
TestWeKnoraBaseURL string
MinerUBaseURL string
TestWeKnoraKBID string
InternalRoutingKnowledgeBaseID string
ExternalRoutingKnowledgeBaseID string
TestWeKnoraAPIKeyFile string
GovernanceSpoolRoot string
IngestionSpoolRoot string
ArtifactFetchMaxBytes int64
WorkerLivenessStaleAfter time.Duration
TestWeKnoraHTTPTimeout time.Duration
TestWeKnoraPollInitial time.Duration
TestWeKnoraPollMax time.Duration
TestWeKnoraStalledAfter time.Duration
TestWeKnoraMaxUploadBytes int64
TestAcceptancePolicyVersion string
// TestAutoReviewPolicy:验收通过后是否自动批准(off|internal|all;默认 internal)。
TestAutoReviewPolicy string
// 目标库所在主机(整库逻辑备份真正执行的地方)。凭据是挂载进来的 0600 ssh
@@ -168,6 +173,7 @@ func Load(getenv func(string) string) (Config, error) {
ProductionReleaseAuthTokenFile: strings.TrimSpace(getenv("PRODUCTION_RELEASE_AUTH_TOKEN_FILE")),
ProductionWeKnoraBaseURL: strings.TrimSpace(getenv("PRODUCTION_WEKNORA_BASE_URL")),
ProductionWeKnoraAPIKeyFile: strings.TrimSpace(getenv("PRODUCTION_WEKNORA_API_KEY_FILE")),
WeKnoraBindingMasterKeyFile: strings.TrimSpace(getenv("WEKNORA_BINDING_MASTER_KEY_FILE")),
PPScanAllowedRoot: strings.TrimSpace(getenv("PP_SCAN_ALLOWED_ROOT")),
PPScanLedgerPath: strings.TrimSpace(getenv("PP_SCAN_LEDGER_PATH")),
PPScanManifestPath: strings.TrimSpace(getenv("PP_SCAN_MANIFEST_PATH")),
@@ -288,6 +294,21 @@ func Load(getenv func(string) string) (Config, error) {
return Config{}, fmt.Errorf("PRODUCTION_WEKNORA_BASE_URL: %w", err)
}
}
if raw := getenv("WEKNORA_ALLOW_PRIVATE_HTTP"); raw != "" {
config.WeKnoraAllowPrivateHTTP, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("WEKNORA_ALLOW_PRIVATE_HTTP: %w", err)
}
}
if raw := getenv("WEKNORA_BINDING_TRUST_TLS_PROXY"); raw != "" {
config.WeKnoraBindingTrustTLSProxy, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("WEKNORA_BINDING_TRUST_TLS_PROXY: %w", err)
}
}
if config.WeKnoraBindingMasterKeyFile != "" && !filepath.IsAbs(config.WeKnoraBindingMasterKeyFile) {
return Config{}, errors.New("WEKNORA_BINDING_MASTER_KEY_FILE must be an absolute path")
}
if config.ProductionWeKnoraAPIKeyFile != "" {
if config.ProductionWeKnoraBaseURL == "" {
return Config{}, errors.New("PRODUCTION_WEKNORA_API_KEY_FILE requires PRODUCTION_WEKNORA_BASE_URL")
+6
View File
@@ -138,6 +138,12 @@ func classifyRole(method, path string) string {
if path == "/api/v1/routing-bindings" && method != http.MethodGet {
return roleAdmin
}
// Recording an endpoint or an API key changes which instance the whole
// platform talks to, and the key is a credential: read is viewer, every
// write (including 测试连接, which spends the key) is admin.
if strings.HasPrefix(path, "/api/v1/weknora-connections") && method != http.MethodGet {
return roleAdmin
}
// Choosing the production base a release writes into is a production
// authority change, exactly like the annotation binding above.
if path == "/api/v1/production-kb-bindings" && method != http.MethodGet {
+10 -2
View File
@@ -411,8 +411,16 @@ func TestClassifyRoleMatrix(t *testing.T) {
http.MethodPost + " /api/v1/users": roleAdmin,
http.MethodPost + " /api/v1/source-connections/c-1/settings/revisions": roleAdmin,
// Choosing a release's production base is a production authority change.
http.MethodPut + " /api/v1/production-kb-bindings": roleAdmin,
http.MethodGet + " /api/v1/production-kb-bindings": roleViewer,
http.MethodPut + " /api/v1/production-kb-bindings": roleAdmin,
http.MethodGet + " /api/v1/production-kb-bindings": roleViewer,
// An endpoint or an API key decides which instance the platform talks
// to; 测试连接 also spends the credential, so every write is admin.
http.MethodGet + " /api/v1/weknora-connections": roleViewer,
http.MethodPost + " /api/v1/weknora-connections/test/test": roleAdmin,
http.MethodPut + " /api/v1/weknora-connections/production": roleAdmin,
// The test-side annotation binding is the same authority as production.
http.MethodGet + " /api/v1/routing-bindings": roleViewer,
http.MethodPut + " /api/v1/routing-bindings": roleAdmin,
http.MethodPost + " /api/v1/review-candidates/tp-1/decision": roleEngineer,
http.MethodPost + " /api/v1/release-batches/rb-1/seal": roleEngineer,
http.MethodPost + " /api/v1/test-publications/start": roleEngineer,
+26 -2
View File
@@ -16,6 +16,10 @@ import (
type ProductionBindingStore interface {
LoadProductionKBBindings(context.Context) (string, string, string, error)
SaveProductionKBBindings(ctx context.Context, internalID, externalID, updatedBy string, now time.Time) error
// ProductionExecutionCounts reports frozen vs still re-targetable release
// items. A binding change never rewrites a target that was already frozen
// when an execution started; the count is how the page says so.
ProductionExecutionCounts(ctx context.Context) (frozen int, retargetable int, err error)
}
// ProductionKnowledgeBaseLister enumerates the knowledge bases of the production
@@ -33,11 +37,26 @@ type productionBindingView struct {
ProductionBaseURL string `json:"production_base_url"`
ProductionConnected bool `json:"production_connected"`
ProductionMessage string `json:"production_message"`
// Frozen / Retargetable describe what a binding change can still affect.
Frozen int `json:"frozen"`
Retargetable int `json:"retargetable"`
}
// WeKnoraConnectionResolver reads the admin-managed connection for one
// environment. When it answers, that endpoint is the only truth.
type WeKnoraConnectionResolver interface {
Resolve(ctx context.Context, environment string) (endpoint string, apiKey string, ok bool)
}
// productionTargetBaseURL is the production endpoint the picker reads from: the
// operator-managed 「服务配置 · 生产地址」 first, the deployment default second.
// connection card first, the operator-managed 「服务配置 · 生产地址」 second, the
// deployment default last.
func (config Config) productionTargetBaseURL(ctx context.Context) string {
if config.WeKnoraConnectionResolver != nil {
if endpoint, _, ok := config.WeKnoraConnectionResolver.Resolve(ctx, "production"); ok {
return endpoint
}
}
if settings, err := config.Store.GetActiveUISettings(ctx); err == nil {
if resolved := strings.TrimSpace(settings.ProductionWeKnoraBaseURL); resolved != "" {
return resolved
@@ -55,7 +74,7 @@ func (config Config) productionKnowledgeBases(ctx context.Context) ([]weknora.Kn
}
baseURL := config.productionTargetBaseURL(ctx)
if baseURL == "" {
return nil, "未配置生产地址(系统设置 → 服务配置)"
return nil, "未配置生产地址(系统设置 → 生产知识库绑定 → 连接卡)"
}
bases, err := config.ProductionKnowledgeBases.ListProductionKnowledgeBases(ctx, baseURL)
if err != nil {
@@ -74,11 +93,16 @@ func (config Config) productionBindingPayload(ctx context.Context) (productionBi
for _, base := range bases {
names[base.ID] = base.Name
}
frozen, retargetable := 0, 0
if frozenItems, retargetableItems, countsErr := config.ProductionBindings.ProductionExecutionCounts(ctx); countsErr == nil {
frozen, retargetable = frozenItems, retargetableItems
}
return productionBindingView{
InternalKBID: storedInternal, ExternalKBID: storedExternal,
InternalKBName: names[storedInternal], ExternalKBName: names[storedExternal],
UpdatedBy: updatedBy, ProductionBaseURL: config.productionTargetBaseURL(ctx),
ProductionConnected: message == "", ProductionMessage: message,
Frozen: frozen, Retargetable: retargetable,
}, nil
}
@@ -18,6 +18,7 @@ type productionBindingStoreFake struct {
internal, external, saver string
savedInternal, savedExternal string
saveCallCount int
frozen, retargetable int
}
func (fake *productionBindingStoreFake) LoadProductionKBBindings(context.Context) (string, string, string, error) {
@@ -32,6 +33,10 @@ func (fake *productionBindingStoreFake) SaveProductionKBBindings(_ context.Conte
return nil
}
func (fake *productionBindingStoreFake) ProductionExecutionCounts(context.Context) (int, int, error) {
return fake.frozen, fake.retargetable, nil
}
type productionListerFake struct {
bases []weknora.KnowledgeBase
err error
+13 -9
View File
@@ -31,12 +31,15 @@ type routingBindingView struct {
ExternalKBID string `json:"external_kb_id"`
InternalEnvFallback bool `json:"internal_env_fallback"`
ExternalEnvFallback bool `json:"external_env_fallback"`
InternalBoundByUI bool `json:"internal_bound_by_ui"`
ExternalBoundByUI bool `json:"external_bound_by_ui"`
InternalKBName string `json:"internal_kb_name"`
ExternalKBName string `json:"external_kb_name"`
UpdatedBy string `json:"updated_by"`
WeKnoraConnected bool `json:"weknora_connected"`
// 取消绑定时必须说清「回退到了哪个库」,否则「留空」等于没说。
InternalFallbackKBID string `json:"internal_fallback_kb_id"`
ExternalFallbackKBID string `json:"external_fallback_kb_id"`
InternalBoundByUI bool `json:"internal_bound_by_ui"`
ExternalBoundByUI bool `json:"external_bound_by_ui"`
InternalKBName string `json:"internal_kb_name"`
ExternalKBName string `json:"external_kb_name"`
UpdatedBy string `json:"updated_by"`
WeKnoraConnected bool `json:"weknora_connected"`
// Replanned / RetiredDuplicates describe what THIS save did to 待入库 items
// that had not been uploaded yet. A plain read reports zeros.
Replanned int `json:"replanned"`
@@ -98,9 +101,10 @@ func (config Config) routingBindingPayload(ctx context.Context, replan postgress
return routingBindingView{
InternalKBID: internal, ExternalKBID: external,
InternalBoundByUI: storedInternal != "", ExternalBoundByUI: storedExternal != "",
InternalEnvFallback: storedInternal == "" && config.InternalRoutingKnowledgeBaseID != "",
ExternalEnvFallback: storedExternal == "" && config.ExternalRoutingKnowledgeBaseID != "",
InternalKBName: names[storedInternal], ExternalKBName: names[storedExternal],
InternalEnvFallback: storedInternal == "" && config.InternalRoutingKnowledgeBaseID != "",
ExternalEnvFallback: storedExternal == "" && config.ExternalRoutingKnowledgeBaseID != "",
InternalFallbackKBID: config.InternalRoutingKnowledgeBaseID, ExternalFallbackKBID: config.ExternalRoutingKnowledgeBaseID,
InternalKBName: names[storedInternal], ExternalKBName: names[storedExternal],
UpdatedBy: updatedBy, WeKnoraConnected: connected,
Replanned: replan.Replanned, RetiredDuplicates: replan.RetiredDuplicates,
}, nil
+27 -8
View File
@@ -177,14 +177,24 @@ type Config struct {
// 它不是运行时开关:生产部署不设置它,那次探测仍然直连目标库逐表计数。
LibraryScopeProbe func(ctx context.Context, scope string) (bool, map[string]int64, error)
// LibraryRetentionVersions/Days 是保留策略;都为 0 = 未设置(不生成清理候选)。
LibraryRetentionVersions int
LibraryRetentionDays int
BackupSchedule BackupScheduleStore
BackupHost BackupHost
BackupRuns *BackupRunTracker
ProductionBindings ProductionBindingStore
ProductionKnowledgeBases ProductionKnowledgeBaseLister
ProductionWeKnoraBaseURL string
LibraryRetentionVersions int
LibraryRetentionDays int
BackupSchedule BackupScheduleStore
BackupHost BackupHost
BackupRuns *BackupRunTracker
ProductionBindings ProductionBindingStore
ProductionKnowledgeBases ProductionKnowledgeBaseLister
ProductionWeKnoraBaseURL string
// WeKnoraConnections 是「连接(地址 + 写-only 密钥)」服务;未接线时三条路由
// 返回 503,页面显示「未接线」而不是假装已配置。
WeKnoraConnections WeKnoraConnections
// WeKnoraAllowPrivateHTTP 允许同网段 http(生产 18093 反代);与客户端、监控
// 探活共用同一个判定。WeKnoraTrustTLSProxy 允许在可信 TLS 反代后录入密钥。
WeKnoraAllowPrivateHTTP bool
WeKnoraTrustTLSProxy bool
// WeKnoraConnectionResolver 读页面保存的连接(地址 + 密钥);页面上显示的
// 生产地址必须来自这里,否则会出现「连接卡写 18093、绑定页还在用旧地址」。
WeKnoraConnectionResolver WeKnoraConnectionResolver
ServiceTargetVerifier ServiceTargetVerifier
Now func() time.Time
RequireWeKnoraReady bool
@@ -421,6 +431,15 @@ func NewHandler(config Config) (http.Handler, error) {
}
config.handleSaveProductionBindings(w, r)
})
mux.HandleFunc("GET /api/v1/weknora-connections", func(w http.ResponseWriter, r *http.Request) {
config.handleWeKnoraConnections(w, r)
})
mux.HandleFunc("POST /api/v1/weknora-connections/{environment}/test", func(w http.ResponseWriter, r *http.Request) {
config.handleWeKnoraConnectionTest(w, r)
})
mux.HandleFunc("PUT /api/v1/weknora-connections/{environment}", func(w http.ResponseWriter, r *http.Request) {
config.handleSaveWeKnoraConnection(w, r)
})
mux.HandleFunc("POST /api/v1/source-catalog/route", func(w http.ResponseWriter, r *http.Request) {
routeCatalogFiles(w, r, config)
})
+153
View File
@@ -0,0 +1,153 @@
package httpapi
import (
"context"
"errors"
"net"
"net/http"
"net/url"
"strings"
"knowledge-governance/internal/weknoraconn"
)
// WeKnoraConnections is the connection service the routes below call. It is
// deliberately narrow: the page may read state, run one real test, and save a
// tested configuration — nothing here triggers a sync, a release or a reparse.
type WeKnoraConnections interface {
View(ctx context.Context, environment string) ([]weknoraconn.View, error)
Test(ctx context.Context, environment string, input weknoraconn.TestInput) (weknoraconn.TestResult, error)
Save(ctx context.Context, environment string, input weknoraconn.SaveInput, actor string) (weknoraconn.View, error)
}
func weKnoraConnectionError(w http.ResponseWriter, err error) {
switch {
case errors.Is(err, weknoraconn.ErrNotFound):
writeJSON(w, http.StatusNotFound, map[string]string{"error": "未知的 WeKnora 环境(只支持 test / production)"})
case errors.Is(err, weknoraconn.ErrStaleRevision):
writeJSON(w, http.StatusConflict, map[string]string{"error": "连接配置已被他人修改,请重新读取后再保存"})
case errors.Is(err, weknoraconn.ErrNotTested):
writeJSON(w, http.StatusBadRequest, map[string]string{
"code": "weknora_connection_not_tested",
"error": "请先点「测试连接」并成功,才能保存这一侧的配置",
})
case errors.Is(err, weknoraconn.ErrStorageUnavailable):
writeJSON(w, http.StatusServiceUnavailable, map[string]string{
"error": "密钥存储不可用:主密钥文件缺失或权限不是 0600,本次未保存任何密钥",
})
case errors.Is(err, weknoraconn.ErrInvalid):
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "连接配置不合法:地址必填,且更换地址必须重新录入密钥"})
default:
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "WeKnora 连接配置处理失败"})
}
}
// weKnoraSecretTransportWithPrivateHTTP decides whether a plaintext key may be
// accepted on this request. It reuses the QA-AI rule (TLS, loopback, trusted
// TLS proxy + same origin) and adds the one case this deployment needs: the
// operator console itself is reached over plain http on a private address, so a
// same-origin fetch from that console is the only accepted non-TLS shape.
func weKnoraSecretTransportWithPrivateHTTP(config Config, r *http.Request) bool {
if qaAISecretTransport(r, config) {
return true
}
if config.WeKnoraTrustTLSProxy && r.Header.Get("X-Forwarded-Proto") == "https" &&
r.Header.Get("Sec-Fetch-Site") == "same-origin" {
origin, err := url.Parse(r.Header.Get("Origin"))
if err == nil && origin.Scheme == "https" {
return true
}
}
if !config.WeKnoraAllowPrivateHTTP {
return false
}
if r.Header.Get("Sec-Fetch-Site") != "same-origin" {
return false
}
origin := strings.TrimSpace(r.Header.Get("Origin"))
if origin == "" {
return false
}
parsed, err := url.Parse(origin)
if err != nil || parsed.Host == "" {
return false
}
if !strings.EqualFold(parsed.Host, r.Host) {
return false
}
host := parsed.Hostname()
if ip := net.ParseIP(host); ip != nil {
return ip.IsPrivate() || ip.IsLoopback() || ip.IsLinkLocalUnicast()
}
return strings.EqualFold(host, "localhost")
}
func (config Config) handleWeKnoraConnections(w http.ResponseWriter, r *http.Request) {
if config.WeKnoraConnections == nil {
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "WeKnora 连接配置未接线"})
return
}
w.Header().Set("Cache-Control", "no-store")
views, err := config.WeKnoraConnections.View(r.Context(), r.PathValue("environment"))
if err != nil {
weKnoraConnectionError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": views})
}
func (config Config) handleWeKnoraConnectionTest(w http.ResponseWriter, r *http.Request) {
if config.WeKnoraConnections == nil {
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "WeKnora 连接配置未接线"})
return
}
w.Header().Set("Cache-Control", "no-store")
var input weknoraconn.TestInput
if err := decodeStrictJSON(r, &input); err != nil {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "请求体不合法"})
return
}
if strings.TrimSpace(input.APIKey) != "" && !weKnoraSecretTransportWithPrivateHTTP(config, r) {
writeJSON(w, http.StatusBadRequest, map[string]string{
"code": "weknora_secret_secure_transport_required",
"error": "密钥仅可在有效 HTTPS、本机回环地址,或已放行的私网治理台同源页面录入;本次未保存、未发送密钥",
})
return
}
result, err := config.WeKnoraConnections.Test(r.Context(), r.PathValue("environment"), input)
if err != nil {
weKnoraConnectionError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": result})
}
func (config Config) handleSaveWeKnoraConnection(w http.ResponseWriter, r *http.Request) {
if config.WeKnoraConnections == nil {
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "WeKnora 连接配置未接线"})
return
}
w.Header().Set("Cache-Control", "no-store")
if _, ok := requireOperationID(w, r); !ok {
return
}
var input weknoraconn.SaveInput
if err := decodeStrictJSON(r, &input); err != nil {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "请求体不合法"})
return
}
if input.KeyAction != weknoraconn.KeyActionClear && strings.TrimSpace(input.APIKey) != "" &&
!weKnoraSecretTransportWithPrivateHTTP(config, r) {
writeJSON(w, http.StatusBadRequest, map[string]string{
"code": "weknora_secret_secure_transport_required",
"error": "密钥仅可在有效 HTTPS、本机回环地址,或已放行的私网治理台同源页面录入;本次未保存、未发送密钥",
})
return
}
view, err := config.WeKnoraConnections.Save(r.Context(), r.PathValue("environment"), input, actorFor(r))
if err != nil {
weKnoraConnectionError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": view})
}
@@ -0,0 +1,174 @@
package httpapi
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
"knowledge-governance/internal/weknoraconn"
)
type weknoraConnectionsFake struct {
views []weknoraconn.View
testResult weknoraconn.TestResult
testErr error
savedResult weknoraconn.View
saveErr error
lastTest weknoraconn.TestInput
lastSave weknoraconn.SaveInput
lastActor string
}
func (fake *weknoraConnectionsFake) View(_ context.Context, environment string) ([]weknoraconn.View, error) {
if environment == "" {
return fake.views, nil
}
if !weknoraconn.ValidEnvironment(environment) {
return nil, weknoraconn.ErrNotFound
}
for _, view := range fake.views {
if view.Environment == environment {
return []weknoraconn.View{view}, nil
}
}
return []weknoraconn.View{{Environment: environment, Verification: weknoraconn.VerificationNotConfigured}}, nil
}
func (fake *weknoraConnectionsFake) Test(_ context.Context, environment string, input weknoraconn.TestInput) (weknoraconn.TestResult, error) {
if !weknoraconn.ValidEnvironment(environment) {
return weknoraconn.TestResult{}, weknoraconn.ErrNotFound
}
fake.lastTest = input
return fake.testResult, fake.testErr
}
func (fake *weknoraConnectionsFake) Save(_ context.Context, environment string, input weknoraconn.SaveInput, actor string) (weknoraconn.View, error) {
if !weknoraconn.ValidEnvironment(environment) {
return weknoraconn.View{}, weknoraconn.ErrNotFound
}
fake.lastSave, fake.lastActor = input, actor
return fake.savedResult, fake.saveErr
}
func weknoraConnectionsHandler(t *testing.T, fake *weknoraConnectionsFake, allowPrivate bool) http.Handler {
t.Helper()
handler, err := NewHandler(Config{
Store: &fakeJobStore{},
WeKnoraConnections: fake,
WeKnoraAllowPrivateHTTP: allowPrivate,
Now: func() time.Time { return time.Date(2026, time.November, 22, 7, 0, 0, 0, time.UTC) },
})
if err != nil {
t.Fatalf("NewHandler: %v", err)
}
return handler
}
func TestWeKnoraConnectionRoutesProjectStateWithoutSecrets(t *testing.T) {
fake := &weknoraConnectionsFake{views: []weknoraconn.View{
{Environment: "test", Endpoint: "http://127.0.0.1:8092", KeyConfigured: true, KeyTail: "9f2c", Verification: weknoraconn.OutcomeOK, LibraryCount: 3, Revision: 2, StorageReady: true},
{Environment: "production", Verification: weknoraconn.VerificationNotConfigured, StorageReady: true},
}}
handler := weknoraConnectionsHandler(t, fake, true)
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/weknora-connections", nil))
if rec.Code != http.StatusOK {
t.Fatalf("status = %d %s", rec.Code, rec.Body.String())
}
if rec.Header().Get("Cache-Control") != "no-store" {
t.Fatalf("cache-control = %q", rec.Header().Get("Cache-Control"))
}
body := rec.Body.String()
if !strings.Contains(body, `"key_tail":"9f2c"`) || strings.Contains(body, "key_ciphertext") || strings.Contains(body, "api_key") {
t.Fatalf("body leaks or loses key projection: %s", body)
}
}
func TestWeKnoraConnectionTestKeepsFourAnswers(t *testing.T) {
for _, outcome := range []string{weknoraconn.OutcomeOK, weknoraconn.OutcomeUnreachable, weknoraconn.OutcomeKeyInvalid, weknoraconn.OutcomeKeyForbidden} {
fake := &weknoraConnectionsFake{testResult: weknoraconn.TestResult{
Environment: "production", Endpoint: "http://172.29.151.11:18093", Outcome: outcome, Message: outcome,
}}
handler := weknoraConnectionsHandler(t, fake, true)
rec := httptest.NewRecorder()
request := httptest.NewRequest(http.MethodPost, "/api/v1/weknora-connections/production/test", strings.NewReader(`{"endpoint":"http://172.29.151.11:18093","key_action":"keep"}`))
request.Header.Set("Content-Type", "application/json")
handler.ServeHTTP(rec, request)
if rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), `"outcome":"`+outcome+`"`) {
t.Fatalf("%s: status = %d body = %s", outcome, rec.Code, rec.Body.String())
}
}
}
func TestWeKnoraConnectionTestRejectsPlainKeyFromAPublicOrigin(t *testing.T) {
fake := &weknoraConnectionsFake{}
handler := weknoraConnectionsHandler(t, fake, true)
rec := httptest.NewRecorder()
request := httptest.NewRequest(http.MethodPost, "/api/v1/weknora-connections/test/test", strings.NewReader(`{"endpoint":"http://127.0.0.1:8092","api_key":"sk-live","key_action":"replace"}`))
request.Header.Set("Content-Type", "application/json")
handler.ServeHTTP(rec, request)
if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), "weknora_secret_secure_transport_required") {
t.Fatalf("status = %d body = %s", rec.Code, rec.Body.String())
}
if fake.lastTest.APIKey != "" {
t.Fatal("a rejected key must never reach the service")
}
}
func TestWeKnoraConnectionTestAcceptsSameOriginPrivateConsole(t *testing.T) {
fake := &weknoraConnectionsFake{testResult: weknoraconn.TestResult{Environment: "test", Outcome: weknoraconn.OutcomeOK}}
handler := weknoraConnectionsHandler(t, fake, true)
rec := httptest.NewRecorder()
request := httptest.NewRequest(http.MethodPost, "/api/v1/weknora-connections/test/test", strings.NewReader(`{"endpoint":"http://127.0.0.1:8092","api_key":"sk-live","key_action":"replace"}`))
request.Host = "172.29.151.10:8088"
request.Header.Set("Content-Type", "application/json")
request.Header.Set("Origin", "http://172.29.151.10:8088")
request.Header.Set("Sec-Fetch-Site", "same-origin")
handler.ServeHTTP(rec, request)
if rec.Code != http.StatusOK {
t.Fatalf("status = %d body = %s", rec.Code, rec.Body.String())
}
if fake.lastTest.APIKey != "sk-live" {
t.Fatalf("service saw key %q", fake.lastTest.APIKey)
}
}
func TestSaveWeKnoraConnectionRequiresIdempotencyKeyAndMapsNotTested(t *testing.T) {
fake := &weknoraConnectionsFake{saveErr: weknoraconn.ErrNotTested}
handler := weknoraConnectionsHandler(t, fake, false)
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, httptest.NewRequest(http.MethodPut, "/api/v1/weknora-connections/production", strings.NewReader(`{"endpoint":"https://prod.example","key_action":"keep","base_revision":1}`)))
if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), "Idempotency-Key") {
t.Fatalf("missing idempotency key: %d %s", rec.Code, rec.Body.String())
}
rec = httptest.NewRecorder()
request := httptest.NewRequest(http.MethodPut, "/api/v1/weknora-connections/production", strings.NewReader(`{"endpoint":"https://prod.example","key_action":"keep","base_revision":1}`))
request.Header.Set("Content-Type", "application/json")
request.Header.Set("Idempotency-Key", "op-1")
handler.ServeHTTP(rec, request)
if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), "weknora_connection_not_tested") {
t.Fatalf("not tested mapping: %d %s", rec.Code, rec.Body.String())
}
}
func TestWeKnoraConnectionUnknownEnvironmentIs404(t *testing.T) {
fake := &weknoraConnectionsFake{}
handler := weknoraConnectionsHandler(t, fake, false)
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/weknora-connections?environment=staging", nil))
// The list route reads the path value, not the query: unknown environments
// only matter on the per-environment routes.
rec = httptest.NewRecorder()
request := httptest.NewRequest(http.MethodPost, "/api/v1/weknora-connections/staging/test", strings.NewReader(`{"endpoint":"https://x.example","key_action":"keep"}`))
request.Header.Set("Content-Type", "application/json")
handler.ServeHTTP(rec, request)
if rec.Code != http.StatusNotFound {
t.Fatalf("status = %d body = %s", rec.Code, rec.Body.String())
}
}
var _ = json.Marshal
+6 -1
View File
@@ -13,6 +13,7 @@ import (
"time"
"knowledge-governance/internal/governance"
"knowledge-governance/internal/platform/weknora"
)
// P10: every configured dependency reports Liveness ("process reachable") and
@@ -197,10 +198,14 @@ func (provider *RealProvider) productionWeKnoraProbe(ctx context.Context, now ti
func (provider *RealProvider) httpProbeOutcome(ctx context.Context, baseURL string, now time.Time) ProbeOutcome {
parsed, err := url.Parse(baseURL)
outcome := ProbeOutcome{ObservedAt: now}
if err != nil || parsed.Scheme != "http" && parsed.Scheme != "https" || parsed.Host == "" {
if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" {
outcome.Reachability = errors.New("探测配置无效")
return outcome
}
if !weknora.HTTPAllowed(baseURL, weknora.HTTPPolicy{AllowPrivateHTTP: provider.allowPrivateHTTP}) {
outcome.Reachability = errors.New("探测配置无效:该地址不被允许(https 或已放行的私网/回环 http)")
return outcome
}
parsed.Path = strings.TrimSuffix(parsed.Path, "/") + "/health"
parsed.RawQuery, parsed.Fragment = "", ""
request, err := http.NewRequestWithContext(ctx, http.MethodGet, parsed.String(), nil)
+6 -1
View File
@@ -50,6 +50,10 @@ type RealProviderConfig struct {
// WorkerStaleAfter bounds how long a missing worker heartbeat still counts
// as alive (P10).
WorkerStaleAfter time.Duration
// AllowPrivateHTTP relaxes the plain-http rule for same-LAN addresses. The
// console probes use the very same judgement as the WeKnora client, so a
// card can never say 「可达」 while the client refuses the same URL.
AllowPrivateHTTP bool
}
type RealProvider struct {
@@ -63,6 +67,7 @@ type RealProvider struct {
productionWeKnoraResolver func(ctx context.Context) string
weknoraReadiness func(ctx context.Context) error
workerStaleAfter time.Duration
allowPrivateHTTP bool
health *healthTracker
}
@@ -103,7 +108,7 @@ func NewRealProvider(config RealProviderConfig) (*RealProvider, error) {
if stale <= 0 {
stale = time.Minute
}
return &RealProvider{db: config.DB, now: config.Now, httpClient: config.HTTPClient, weknoraBaseURL: strings.TrimSpace(config.WeKnoraBaseURL), minerUBaseURL: strings.TrimSpace(config.MinerUBaseURL), testWeKnoraResolver: config.TestWeKnoraResolver, productionWeKnoraBaseURL: strings.TrimSpace(config.ProductionWeKnoraBaseURL), productionWeKnoraResolver: config.ProductionWeKnoraResolver, weknoraReadiness: config.WeKnoraReadiness, workerStaleAfter: stale, health: newHealthTracker()}, nil
return &RealProvider{db: config.DB, now: config.Now, httpClient: config.HTTPClient, weknoraBaseURL: strings.TrimSpace(config.WeKnoraBaseURL), minerUBaseURL: strings.TrimSpace(config.MinerUBaseURL), testWeKnoraResolver: config.TestWeKnoraResolver, productionWeKnoraBaseURL: strings.TrimSpace(config.ProductionWeKnoraBaseURL), productionWeKnoraResolver: config.ProductionWeKnoraResolver, weknoraReadiness: config.WeKnoraReadiness, workerStaleAfter: stale, allowPrivateHTTP: config.AllowPrivateHTTP, health: newHealthTracker()}, nil
}
func (provider *RealProvider) Overview(ctx context.Context) (governance.MonitorOverview, error) {
@@ -0,0 +1,3 @@
DROP TABLE IF EXISTS weknora_environment_connection_tests;
DROP TABLE IF EXISTS weknora_environment_connection_history;
DROP TABLE IF EXISTS weknora_environment_connections;
@@ -0,0 +1,45 @@
-- 连接是「地址 + 写-only 密钥」的一份状态,绑定仍然是「对内/对外目标库」的另一份
-- 状态(routing_kb_bindings / production_kb_bindings)。两者刻意不合并:现场那张
-- 把两者塞进一张表的孤表正是重复列的来源。
--
-- 编号从 000083 起:现场 0.9.0 的 schema_migrations 已登记到 82,而迁移器按号跳过、
-- 没有顺序守卫 —— 76..82 号会被静默丢弃。仓内最大号到 75 不影响 83 的排序与执行。
CREATE TABLE weknora_environment_connections (
environment VARCHAR(16) PRIMARY KEY CHECK (environment IN ('test','production')),
revision BIGINT NOT NULL DEFAULT 1 CHECK (revision > 0),
endpoint TEXT NOT NULL DEFAULT '',
key_ciphertext BYTEA NOT NULL DEFAULT '\x',
key_tail VARCHAR(8) NOT NULL DEFAULT '',
verification TEXT NOT NULL DEFAULT 'not_configured'
CHECK (verification IN ('not_configured','ok','unreachable','key_invalid','key_forbidden')),
library_count INTEGER NOT NULL DEFAULT 0 CHECK (library_count >= 0),
checked_at TIMESTAMPTZ,
updated_by TEXT NOT NULL DEFAULT '',
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
-- 历史只记「有没有配过密钥」,不记尾号也不记密文:一个可审计的时间线不需要能
-- 反推出任何一位密钥。
CREATE TABLE weknora_environment_connection_history (
environment VARCHAR(16) NOT NULL CHECK (environment IN ('test','production')),
revision BIGINT NOT NULL,
endpoint TEXT NOT NULL,
key_configured BOOLEAN NOT NULL,
verification TEXT NOT NULL,
actor TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
PRIMARY KEY (environment, revision)
);
-- 「测通才可保存」需要一条可核对的证据:这次测试用的是哪个地址、哪把密钥(只存
-- 指纹)、结论如何。保存时按 (environment, endpoint, key_fingerprint, ok) 匹配。
CREATE TABLE weknora_environment_connection_tests (
environment VARCHAR(16) PRIMARY KEY CHECK (environment IN ('test','production')),
endpoint TEXT NOT NULL,
key_fingerprint CHAR(64) NOT NULL CHECK (key_fingerprint ~ '^[0-9a-f]{64}$'),
outcome TEXT NOT NULL
CHECK (outcome IN ('ok','unreachable','key_invalid','key_forbidden')),
library_count INTEGER NOT NULL DEFAULT 0 CHECK (library_count >= 0),
message TEXT NOT NULL DEFAULT '',
checked_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
+20 -12
View File
@@ -11,51 +11,59 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) {
if err != nil {
t.Fatalf("loadMigrations() error = %v", err)
}
if len(migrations) != 75 {
t.Fatalf("migration count = %d, want 75", len(migrations))
if len(migrations) != 76 {
t.Fatalf("migration count = %d, want 76", len(migrations))
}
// 83 把「连接(地址 + 写-only 密钥)」从文件引用搬进治理库;编号必须 ≥83,
// 因为现场 0.9.0 的 schema_migrations 已到 82,迁移器按号跳过且无顺序守卫。
if connections := migrations[len(migrations)-1]; connections.Version != 83 ||
!strings.Contains(connections.UpSQL, "weknora_environment_connections") ||
!strings.Contains(connections.UpSQL, "key_ciphertext") ||
!strings.Contains(connections.DownSQL, "DROP TABLE IF EXISTS weknora_environment_connections") {
t.Fatalf("migration 83 = %#v", connections)
}
// 75 允许"建立目标权威基线"作为独立业务作业,并与 sync/restore 共用写互斥。
if baseline := migrations[len(migrations)-1]; baseline.Version != 75 ||
if baseline := migrations[len(migrations)-2]; baseline.Version != 75 ||
!strings.Contains(baseline.UpSQL, "library_jobs_write_target") ||
!strings.Contains(baseline.UpSQL, "'baseline'") {
t.Fatalf("migration 75 = %#v", baseline)
}
// 74 记录封存执行器的运行时状态:页面可用性来自真实观测,不来自配置字符串。
if executor := migrations[len(migrations)-2]; executor.Version != 74 ||
if executor := migrations[len(migrations)-3]; executor.Version != 74 ||
!strings.Contains(executor.UpSQL, "library_executor_status") {
t.Fatalf("migration 74 = %#v", executor)
}
// 73 记录死信精确解除:保留上游行,只绑定指纹、重放引用与观测摘要。
if release := migrations[len(migrations)-3]; release.Version != 73 ||
if release := migrations[len(migrations)-4]; release.Version != 73 ||
!strings.Contains(release.UpSQL, "library_dead_letter_releases") {
t.Fatalf("migration 73 = %#v", release)
}
// 72 让维护占用按实例互斥(internal/external 不再各有各的锁)。
if instance := migrations[len(migrations)-4]; instance.Version != 72 ||
if instance := migrations[len(migrations)-5]; instance.Version != 72 ||
!strings.Contains(instance.UpSQL, "library_instance_maintenance") {
t.Fatalf("migration 72 = %#v", instance)
}
// 71 让维护记录能区分实例级维护与仅治理库互斥。
if level := migrations[len(migrations)-5]; level.Version != 71 ||
if level := migrations[len(migrations)-6]; level.Version != 71 ||
!strings.Contains(level.UpSQL, "level") || !strings.Contains(level.UpSQL, "ingress_state") {
t.Fatalf("migration 71 = %#v", level)
}
if maint := migrations[len(migrations)-6]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
if maint := migrations[len(migrations)-7]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
t.Fatalf("migration 70 = %#v", maint)
}
if tail := migrations[len(migrations)-7]; tail.Version != 69 ||
if tail := migrations[len(migrations)-8]; tail.Version != 69 ||
!strings.Contains(tail.UpSQL, "library_jobs_write_target") {
t.Fatalf("migration 69 = %#v", tail)
}
if restore := migrations[len(migrations)-8]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
if restore := migrations[len(migrations)-9]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
t.Fatalf("migration 68 = %#v", restore)
}
if last := migrations[len(migrations)-9]; last.Version != 67 ||
if last := migrations[len(migrations)-10]; last.Version != 67 ||
!strings.Contains(last.UpSQL, "library_release_authorizations") ||
!strings.Contains(last.UpSQL, "params_digest") {
t.Fatalf("migration 67 = %#v", last)
}
if flow := migrations[len(migrations)-10]; flow.Version != 66 ||
if flow := migrations[len(migrations)-11]; flow.Version != 66 ||
!strings.Contains(flow.UpSQL, "CREATE TABLE library_versions") ||
!strings.Contains(flow.UpSQL, "library_jobs_active") {
t.Fatalf("migration 66 = %#v", flow)
@@ -0,0 +1,203 @@
package postgres
import (
"context"
"errors"
"fmt"
"time"
"github.com/jackc/pgx/v5"
)
// WeKnoraConnection is one environment's 地址 + 写-only 密钥. The ciphertext is
// opened only in the service layer; everything below this line treats it as an
// opaque blob so no query result can accidentally be rendered as a secret.
type WeKnoraConnection struct {
Environment string
Revision int64
Endpoint string
KeyCiphertext []byte
KeyTail string
Verification string
LibraryCount int
CheckedAt *time.Time
UpdatedBy string
UpdatedAt time.Time
}
// WeKnoraConnectionTest is the evidence a save needs: which endpoint, which key
// (fingerprint only) and what the last real listing said.
type WeKnoraConnectionTest struct {
Environment string
Endpoint string
KeyFingerprint string
Outcome string
LibraryCount int
Message string
CheckedAt time.Time
}
// LoadWeKnoraConnections reads both environments. A missing row is simply absent
// from the result: 「未配置」 is a state, not an error.
func (s *Store) LoadWeKnoraConnections(ctx context.Context) ([]WeKnoraConnection, error) {
rows, err := s.db.Query(ctx, `
SELECT environment,revision,endpoint,key_ciphertext,key_tail,verification,library_count,checked_at,updated_by,updated_at
FROM weknora_environment_connections
ORDER BY environment`)
if err != nil {
return nil, errors.New("load weknora connections")
}
defer rows.Close()
connections := make([]WeKnoraConnection, 0, 2)
for rows.Next() {
var connection WeKnoraConnection
if err := rows.Scan(&connection.Environment, &connection.Revision, &connection.Endpoint,
&connection.KeyCiphertext, &connection.KeyTail, &connection.Verification,
&connection.LibraryCount, &connection.CheckedAt, &connection.UpdatedBy, &connection.UpdatedAt); err != nil {
return nil, errors.New("load weknora connections")
}
connections = append(connections, connection)
}
if rows.Err() != nil {
return nil, errors.New("load weknora connections")
}
return connections, nil
}
// LoadWeKnoraConnection reads one environment. The boolean is false when the
// environment was never configured.
func (s *Store) LoadWeKnoraConnection(ctx context.Context, environment string) (WeKnoraConnection, bool, error) {
var connection WeKnoraConnection
err := s.db.QueryRow(ctx, `
SELECT environment,revision,endpoint,key_ciphertext,key_tail,verification,library_count,checked_at,updated_by,updated_at
FROM weknora_environment_connections WHERE environment=$1`, environment).
Scan(&connection.Environment, &connection.Revision, &connection.Endpoint,
&connection.KeyCiphertext, &connection.KeyTail, &connection.Verification,
&connection.LibraryCount, &connection.CheckedAt, &connection.UpdatedBy, &connection.UpdatedAt)
if errors.Is(err, pgx.ErrNoRows) {
return WeKnoraConnection{}, false, nil
}
if err != nil {
return WeKnoraConnection{}, false, errors.New("load weknora connection")
}
return connection, true, nil
}
// SaveWeKnoraConnection writes one revision and its history row in a single
// transaction. The advisory lock is per environment so two concurrent saves
// cannot both pick the same revision.
func (s *Store) SaveWeKnoraConnection(ctx context.Context, connection WeKnoraConnection, now time.Time) error {
if now.IsZero() {
return errors.New("weknora connection save requires a timestamp")
}
tx, err := s.db.Begin(ctx)
if err != nil {
return fmt.Errorf("begin weknora connection save: %w", err)
}
defer func() { _ = tx.Rollback(ctx) }()
if _, err := tx.Exec(ctx, `SELECT pg_advisory_xact_lock(hashtext('weknora_connection:'||$1))`, connection.Environment); err != nil {
return fmt.Errorf("lock weknora connection: %w", err)
}
if _, err := tx.Exec(ctx, `
INSERT INTO weknora_environment_connections(environment,revision,endpoint,key_ciphertext,key_tail,verification,library_count,checked_at,updated_by,updated_at)
VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
ON CONFLICT(environment) DO UPDATE SET
revision=EXCLUDED.revision,
endpoint=EXCLUDED.endpoint,
key_ciphertext=EXCLUDED.key_ciphertext,
key_tail=EXCLUDED.key_tail,
verification=EXCLUDED.verification,
library_count=EXCLUDED.library_count,
checked_at=EXCLUDED.checked_at,
updated_by=EXCLUDED.updated_by,
updated_at=EXCLUDED.updated_at`,
connection.Environment, connection.Revision, connection.Endpoint, connection.KeyCiphertext,
connection.KeyTail, connection.Verification, connection.LibraryCount, connection.CheckedAt,
connection.UpdatedBy, now); err != nil {
return errors.New("save weknora connection")
}
if _, err := tx.Exec(ctx, `
INSERT INTO weknora_environment_connection_history(environment,revision,endpoint,key_configured,verification,actor,created_at)
VALUES($1,$2,$3,$4,$5,$6,$7)
ON CONFLICT(environment,revision) DO NOTHING`,
connection.Environment, connection.Revision, connection.Endpoint, len(connection.KeyCiphertext) > 0,
connection.Verification, connection.UpdatedBy, now); err != nil {
return errors.New("record weknora connection history")
}
if err := tx.Commit(ctx); err != nil {
return fmt.Errorf("commit weknora connection save: %w", err)
}
return nil
}
// SaveWeKnoraConnectionTest stores the outcome of the real listing a save will
// later point at. Only the key fingerprint is kept — never the key.
func (s *Store) SaveWeKnoraConnectionTest(ctx context.Context, result WeKnoraConnectionTest, now time.Time) error {
if now.IsZero() {
return errors.New("weknora connection test requires a timestamp")
}
if _, err := s.db.Exec(ctx, `
INSERT INTO weknora_environment_connection_tests(environment,endpoint,key_fingerprint,outcome,library_count,message,checked_at)
VALUES($1,$2,$3,$4,$5,$6,$7)
ON CONFLICT(environment) DO UPDATE SET
endpoint=EXCLUDED.endpoint,
key_fingerprint=EXCLUDED.key_fingerprint,
outcome=EXCLUDED.outcome,
library_count=EXCLUDED.library_count,
message=EXCLUDED.message,
checked_at=EXCLUDED.checked_at`,
result.Environment, result.Endpoint, result.KeyFingerprint, result.Outcome,
result.LibraryCount, result.Message, now); err != nil {
return errors.New("save weknora connection test")
}
return nil
}
// LoadWeKnoraConnectionTest reads the last test for one environment.
func (s *Store) LoadWeKnoraConnectionTest(ctx context.Context, environment string) (WeKnoraConnectionTest, bool, error) {
var result WeKnoraConnectionTest
err := s.db.QueryRow(ctx, `
SELECT environment,endpoint,key_fingerprint,outcome,library_count,message,checked_at
FROM weknora_environment_connection_tests WHERE environment=$1`, environment).
Scan(&result.Environment, &result.Endpoint, &result.KeyFingerprint, &result.Outcome,
&result.LibraryCount, &result.Message, &result.CheckedAt)
if errors.Is(err, pgx.ErrNoRows) {
return WeKnoraConnectionTest{}, false, nil
}
if err != nil {
return WeKnoraConnectionTest{}, false, errors.New("load weknora connection test")
}
return result, true, nil
}
// UpdateWeKnoraConnectionVerification refreshes the card state without touching
// the saved endpoint or ciphertext.
func (s *Store) UpdateWeKnoraConnectionVerification(ctx context.Context, environment, verification string, libraryCount int, checkedAt time.Time, now time.Time) error {
if _, err := s.db.Exec(ctx, `
UPDATE weknora_environment_connections
SET verification=$2, library_count=$3, checked_at=$4, updated_at=$5
WHERE environment=$1`, environment, verification, libraryCount, checkedAt, now); err != nil {
return errors.New("update weknora connection verification")
}
return nil
}
// ProductionExecutionCounts reports, for executions that are still in flight,
// how many items already have a frozen production target and how many do not yet.
// A production binding change never rewrites the frozen ones: an execution that
// already started keeps the knowledge base it was authorized against. Lifetime
// counts are deliberately excluded — completed executions are history, not
// something a binding change could still affect.
func (s *Store) ProductionExecutionCounts(ctx context.Context) (int, int, error) {
var frozen, retargetable int
if err := s.db.QueryRow(ctx, `
SELECT
COUNT(*) FILTER (WHERE item.target_knowledge_base_id <> ''),
COUNT(*) FILTER (WHERE item.target_knowledge_base_id = '')
FROM release_item_executions item
JOIN release_executions execution ON execution.id = item.release_execution_id
WHERE execution.state IN ('pending','running')`).Scan(&frozen, &retargetable); err != nil {
return 0, 0, errors.New("load production execution counts")
}
return frozen, retargetable, nil
}
@@ -0,0 +1,118 @@
package postgres
import (
"context"
"os"
"testing"
"time"
"github.com/jackc/pgx/v5/pgxpool"
)
// 连接(地址 + 写-only 密钥)是新的持久状态:一环境一行、修订递增、历史只记
// 「有没有配过密钥」。测试必须证明 000083 真能 up/down,而不是只证明 SQL 解析通过。
func TestWeKnoraConnectionsMigrationUpDownAndStore(t *testing.T) {
databaseURL := isolatedIntegrationDatabaseURL(t, os.Getenv("TEST_DATABASE_URL"))
if databaseURL == "" {
t.Skip("TEST_DATABASE_URL is not set")
}
ctx := context.Background()
pool, err := pgxpool.New(ctx, databaseURL)
if err != nil {
t.Fatal(err)
}
defer pool.Close()
if err = ApplyMigrations(ctx, pool); err != nil {
t.Fatalf("apply migrations: %v", err)
}
var applied bool
if err = pool.QueryRow(ctx, "SELECT EXISTS (SELECT 1 FROM schema_migrations WHERE version = 83)").Scan(&applied); err != nil || !applied {
t.Fatalf("migration 83 not recorded: %v %v", applied, err)
}
store := NewStore(pool)
now := time.Date(2026, time.November, 22, 7, 0, 0, 0, time.UTC)
checked := now.Add(-time.Minute)
connection := WeKnoraConnection{
Environment: "production",
Revision: 2,
Endpoint: "http://172.29.151.11:18093",
KeyCiphertext: []byte{1, 2, 3, 4},
KeyTail: "9f2c",
Verification: "ok",
LibraryCount: 4,
CheckedAt: &checked,
UpdatedBy: "admin",
}
if err := store.SaveWeKnoraConnection(ctx, connection, now); err != nil {
t.Fatalf("save connection: %v", err)
}
loaded, exists, err := store.LoadWeKnoraConnection(ctx, "production")
if err != nil || !exists {
t.Fatalf("load connection: %v %v", exists, err)
}
if loaded.Endpoint != connection.Endpoint || loaded.Revision != 2 || loaded.KeyTail != "9f2c" || string(loaded.KeyCiphertext) != string(connection.KeyCiphertext) {
t.Fatalf("loaded = %+v", loaded)
}
var configured bool
var actor string
if err := pool.QueryRow(ctx, `SELECT key_configured,actor FROM weknora_environment_connection_history WHERE environment='production' AND revision=2`).Scan(&configured, &actor); err != nil {
t.Fatalf("history row: %v", err)
}
if !configured || actor != "admin" {
t.Fatalf("history = %v %q", configured, actor)
}
// 历史里不能出现尾号或密文:只有布尔。
var historyColumns int
if err := pool.QueryRow(ctx, `SELECT COUNT(*) FROM information_schema.columns WHERE table_schema=current_schema() AND table_name='weknora_environment_connection_history' AND column_name IN ('key_tail','key_ciphertext')`).Scan(&historyColumns); err != nil {
t.Fatal(err)
}
if historyColumns != 0 {
t.Fatalf("history table exposes %d secret columns", historyColumns)
}
// 测试证据:同一环境只保留最后一次,且只存密钥指纹。
fingerprint := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
if err := store.SaveWeKnoraConnectionTest(ctx, WeKnoraConnectionTest{
Environment: "production", Endpoint: connection.Endpoint, KeyFingerprint: fingerprint,
Outcome: "ok", LibraryCount: 4, Message: "接口可达",
}, now); err != nil {
t.Fatalf("save test evidence: %v", err)
}
proof, found, err := store.LoadWeKnoraConnectionTest(ctx, "production")
if err != nil || !found || proof.KeyFingerprint != fingerprint || proof.Outcome != "ok" {
t.Fatalf("load test evidence = %+v %v %v", proof, found, err)
}
// 冻结/未冻结计数按 target_knowledge_base_id 判定,不能用 IS NULL。
frozen, retargetable, err := store.ProductionExecutionCounts(ctx)
if err != nil {
t.Fatalf("production execution counts: %v", err)
}
if frozen != 0 || retargetable != 0 {
t.Fatalf("empty execution counts = %d/%d", frozen, retargetable)
}
// down 必须只删这三张新表,不碰既有绑定表。
if err := RollbackLatestMigration(ctx, pool); err != nil {
t.Fatalf("rollback 83: %v", err)
}
for _, table := range []string{"weknora_environment_connections", "weknora_environment_connection_history", "weknora_environment_connection_tests"} {
var present bool
if err := pool.QueryRow(ctx, `SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_schema=current_schema() AND table_name=$1)`, table).Scan(&present); err != nil {
t.Fatal(err)
}
if present {
t.Fatalf("%s survived the down migration", table)
}
}
for _, table := range []string{"routing_kb_bindings", "production_kb_bindings"} {
var present bool
if err := pool.QueryRow(ctx, `SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_schema=current_schema() AND table_name=$1)`, table).Scan(&present); err != nil {
t.Fatal(err)
}
if !present {
t.Fatalf("%s must not be dropped by migration 83 down", table)
}
}
}
+49 -1
View File
@@ -48,6 +48,43 @@ type ClientConfig struct {
Timeout time.Duration
MaxResponseBytes int64
AllowDockerHTTP bool
// AllowPrivateHTTP relaxes the http-only rule for RFC1918, link-local and
// ULA literals. It exists because the production instance sits behind a
// same-LAN nginx that speaks plain http; https stays the default and any
// public http host is still refused.
AllowPrivateHTTP bool
}
// HTTPPolicy is the single reachability judgement shared by the WeKnora client
// and the console probes: two callers must never disagree about whether a
// configured endpoint is acceptable.
type HTTPPolicy struct {
AllowPrivateHTTP bool
AllowDockerHTTP bool
}
// HTTPAllowed reports whether baseURL may be called at all. https is always
// allowed; http only for loopback, an opted-in private address, or (legacy)
// a single-label docker host.
func HTTPAllowed(rawURL string, policy HTTPPolicy) bool {
parsed, err := url.Parse(strings.TrimSpace(rawURL))
if err != nil || parsed.Host == "" || parsed.User != nil {
return false
}
switch parsed.Scheme {
case "https":
return true
case "http":
host := parsed.Hostname()
if isLoopbackHost(host) {
return true
}
if policy.AllowPrivateHTTP && isPrivateHost(host) {
return true
}
return policy.AllowDockerHTTP && isSingleLabelDockerHost(host)
}
return false
}
type Client struct {
@@ -65,7 +102,7 @@ func NewClient(config ClientConfig) (*Client, error) {
if baseURL.Scheme == "" || baseURL.Host == "" || baseURL.User != nil || baseURL.RawQuery != "" || baseURL.Fragment != "" {
return nil, errors.New("invalid WeKnora base URL")
}
if baseURL.Scheme != "https" && !(baseURL.Scheme == "http" && (isLoopbackHost(baseURL.Hostname()) || (config.AllowDockerHTTP && isSingleLabelDockerHost(baseURL.Hostname())))) {
if !HTTPAllowed(config.BaseURL, HTTPPolicy{AllowPrivateHTTP: config.AllowPrivateHTTP, AllowDockerHTTP: config.AllowDockerHTTP}) {
return nil, errors.New("WeKnora base URL must use HTTPS")
}
baseURL.Path = strings.TrimRight(baseURL.Path, "/")
@@ -99,6 +136,17 @@ func isLoopbackHost(host string) bool {
return ip != nil && ip.IsLoopback()
}
// isPrivateHost reports the addresses a same-LAN deployment legitimately uses:
// RFC1918, link-local and IPv6 ULA. A public name is never private, so opting
// in cannot widen the client to the internet.
func isPrivateHost(host string) bool {
ip := net.ParseIP(host)
if ip == nil {
return false
}
return ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()
}
func isSingleLabelDockerHost(host string) bool {
if host == "" || strings.Contains(host, ".") || net.ParseIP(host) != nil || len(host) > 63 {
return false
@@ -0,0 +1,44 @@
package weknora
import "testing"
func TestHTTPAllowedSharesOneJudgement(t *testing.T) {
cases := []struct {
name string
url string
policy HTTPPolicy
want bool
}{
{"https always", "https://weknora.example", HTTPPolicy{}, true},
{"loopback http", "http://127.0.0.1:8092", HTTPPolicy{}, true},
{"localhost http", "http://localhost:8092", HTTPPolicy{}, true},
{"private http refused by default", "http://172.29.151.11:18093", HTTPPolicy{}, false},
{"private http allowed when opted in", "http://172.29.151.11:18093", HTTPPolicy{AllowPrivateHTTP: true}, true},
{"rfc1918 /8", "http://10.1.2.3", HTTPPolicy{AllowPrivateHTTP: true}, true},
{"rfc1918 /16", "http://192.168.1.10", HTTPPolicy{AllowPrivateHTTP: true}, true},
{"link-local", "http://169.254.10.10", HTTPPolicy{AllowPrivateHTTP: true}, true},
{"public http still refused", "http://203.0.113.9", HTTPPolicy{AllowPrivateHTTP: true}, false},
{"public name still refused", "http://weknora.example", HTTPPolicy{AllowPrivateHTTP: true}, false},
{"docker single label opt-in", "http://weknora", HTTPPolicy{AllowDockerHTTP: true}, true},
{"docker single label off", "http://weknora", HTTPPolicy{}, false},
{"credentials refused", "http://user:pass@127.0.0.1:8092", HTTPPolicy{}, false},
{"empty host", "http://", HTTPPolicy{}, false},
{"other scheme", "ftp://127.0.0.1", HTTPPolicy{}, false},
}
for _, testCase := range cases {
if got := HTTPAllowed(testCase.url, testCase.policy); got != testCase.want {
t.Fatalf("%s: HTTPAllowed(%q, %+v) = %v, want %v", testCase.name, testCase.url, testCase.policy, got, testCase.want)
}
}
}
func TestNewClientAcceptsPrivateHTTPOnlyWhenOptedIn(t *testing.T) {
base := ClientConfig{BaseURL: "http://172.29.151.11:18093", APIKey: "k", Timeout: 1}
if _, err := NewClient(base); err == nil {
t.Fatal("private http must be refused without the opt-in")
}
base.AllowPrivateHTTP = true
if _, err := NewClient(base); err != nil {
t.Fatalf("private http must be accepted with the opt-in: %v", err)
}
}
+21 -41
View File
@@ -1,55 +1,35 @@
package qaopsai
import (
"crypto/aes"
"crypto/cipher"
"crypto/rand"
"fmt"
"os"
"knowledge-governance/internal/sealedsecret"
)
// The independently provisioned master key never lives in source, settings JSON or database backups.
func (s *Store) masterKey() ([]byte, error) {
info, err := os.Lstat(s.options.KeyFile)
if err != nil || !info.Mode().IsRegular() || info.Mode().Perm() != 0600 {
return nil, ErrUnavailable
}
raw, err := os.ReadFile(s.options.KeyFile)
if err != nil || len(raw) != 32 {
return nil, ErrUnavailable
}
return raw, nil
}
func (s *Store) aead() (cipher.AEAD, error) {
key, err := s.masterKey()
if err != nil {
return nil, err
}
block, err := aes.NewCipher(key)
if err != nil {
return nil, ErrUnavailable
}
return cipher.NewGCM(block)
}
// QA-AI keeps one write-only credential per revision. The AES-GCM convention
// itself lives in internal/sealedsecret so a second feature cannot grow a
// second, slightly different crypto path; only the AAD domain and the error
// vocabulary stay here.
const qaAISecretScope = "qa-ai"
func (s *Store) seal(secret string, revision int64) ([]byte, error) {
aead, err := s.aead()
key, err := sealedsecret.LoadKeyFile(s.options.KeyFile)
if err != nil {
return nil, err
}
nonce := make([]byte, aead.NonceSize())
if _, err = rand.Read(nonce); err != nil {
return nil, ErrUnavailable
}
return aead.Seal(nonce, nonce, []byte(secret), []byte(fmt.Sprintf("qa-ai:%s:%d", s.tenant, revision))), nil
}
func (s *Store) unseal(sealed []byte, revision int64) (string, error) {
aead, err := s.aead()
if err != nil || len(sealed) < aead.NonceSize() {
return "", ErrUnavailable
sealed, err := sealedsecret.Seal(key, secret, sealedsecret.AAD(qaAISecretScope, s.tenant, revision))
if err != nil {
return nil, ErrUnavailable
}
raw, err := aead.Open(nil, sealed[:aead.NonceSize()], sealed[aead.NonceSize():], []byte(fmt.Sprintf("qa-ai:%s:%d", s.tenant, revision)))
return sealed, nil
}
func (s *Store) unseal(sealed []byte, revision int64) (string, error) {
key, err := sealedsecret.LoadKeyFile(s.options.KeyFile)
if err != nil {
return "", ErrUnavailable
}
return string(raw), nil
plain, err := sealedsecret.Open(key, sealed, sealedsecret.AAD(qaAISecretScope, s.tenant, revision))
if err != nil {
return "", ErrUnavailable
}
return plain, nil
}
+3 -1
View File
@@ -9,6 +9,8 @@ import (
"net/url"
"strings"
"time"
"knowledge-governance/internal/sealedsecret"
)
type Options struct {
@@ -67,7 +69,7 @@ func (s *Store) readSettings(ctx context.Context, q settingsQuery) (privateSetti
return out, ErrUnavailable
}
out.KeyConfigured = len(out.sealed) > 0
_, keyErr := s.masterKey()
_, keyErr := sealedsecret.LoadKeyFile(s.options.KeyFile)
out.StorageReady = keyErr == nil
return out, nil
}
+91
View File
@@ -0,0 +1,91 @@
// Package sealedsecret holds the one AES-GCM convention this platform uses to
// keep a write-only credential (model key, WeKnora key) inside a database row
// without ever storing the plaintext or a reversible copy elsewhere.
//
// Two rules make it safe to have only one implementation:
// - the master key is an independently provisioned 32-byte 0600 file, never
// in source, settings JSON or database backups;
// - every ciphertext is bound to a caller-supplied AAD (tenant + revision),
// so a sealed value cannot be replayed onto a different row or revision.
package sealedsecret
import (
"crypto/aes"
"crypto/cipher"
"crypto/rand"
"errors"
"fmt"
"os"
)
// ErrUnavailable means the master key is not usable, so sealing and opening are
// both impossible. Callers degrade honestly (they must not pretend it works).
var ErrUnavailable = errors.New("sealed secret storage is unavailable")
// KeySize is the only accepted master-key length (AES-256).
const KeySize = 32
// LoadKeyFile reads the master key. A missing file, a non-regular file, group or
// other permissions, or a wrong length are all ErrUnavailable: a half-configured
// secret store must never be silently substituted by a weaker one.
func LoadKeyFile(path string) ([]byte, error) {
if path == "" {
return nil, ErrUnavailable
}
info, err := os.Lstat(path)
if err != nil || !info.Mode().IsRegular() || info.Mode().Perm() != 0o600 {
return nil, ErrUnavailable
}
raw, err := os.ReadFile(path)
if err != nil || len(raw) != KeySize {
return nil, ErrUnavailable
}
return raw, nil
}
func aead(key []byte) (cipher.AEAD, error) {
if len(key) != KeySize {
return nil, ErrUnavailable
}
block, err := aes.NewCipher(key)
if err != nil {
return nil, ErrUnavailable
}
return cipher.NewGCM(block)
}
// Seal returns nonce||ciphertext bound to aad.
func Seal(key []byte, plaintext, aad string) ([]byte, error) {
sealer, err := aead(key)
if err != nil {
return nil, err
}
nonce := make([]byte, sealer.NonceSize())
if _, err = rand.Read(nonce); err != nil {
return nil, ErrUnavailable
}
return sealer.Seal(nonce, nonce, []byte(plaintext), []byte(aad)), nil
}
// Open reverses Seal. A different aad, a truncated value or a rotated key all
// return ErrUnavailable rather than an empty credential.
func Open(key, sealed []byte, aad string) (string, error) {
opener, err := aead(key)
if err != nil {
return "", err
}
if len(sealed) < opener.NonceSize() {
return "", ErrUnavailable
}
raw, err := opener.Open(nil, sealed[:opener.NonceSize()], sealed[opener.NonceSize():], []byte(aad))
if err != nil {
return "", ErrUnavailable
}
return string(raw), nil
}
// AAD builds the canonical associated data for one row revision. Every caller
// goes through it so two features cannot accidentally share a binding domain.
func AAD(scope, subject string, revision int64) string {
return fmt.Sprintf("%s:%s:%d", scope, subject, revision)
}
@@ -0,0 +1,73 @@
package sealedsecret
import (
"bytes"
"os"
"path/filepath"
"testing"
)
func writeKey(t *testing.T, content []byte, mode os.FileMode) string {
t.Helper()
path := filepath.Join(t.TempDir(), "master.key")
if err := os.WriteFile(path, content, mode); err != nil {
t.Fatalf("write key file: %v", err)
}
if err := os.Chmod(path, mode); err != nil {
t.Fatalf("chmod key file: %v", err)
}
return path
}
func TestSealOpenRoundTripBindsAAD(t *testing.T) {
key := bytes.Repeat([]byte{0x7a}, KeySize)
sealed, err := Seal(key, "sk-live-1234", AAD("weknora-connection", "test", 3))
if err != nil {
t.Fatalf("Seal() error = %v", err)
}
if bytes.Contains(sealed, []byte("sk-live-1234")) {
t.Fatal("ciphertext must not contain the plaintext")
}
plain, err := Open(key, sealed, AAD("weknora-connection", "test", 3))
if err != nil || plain != "sk-live-1234" {
t.Fatalf("Open() = %q, %v", plain, err)
}
if _, err := Open(key, sealed, AAD("weknora-connection", "test", 4)); err == nil {
t.Fatal("a different revision must not open the same ciphertext")
}
if _, err := Open(key, sealed, AAD("weknora-connection", "production", 3)); err == nil {
t.Fatal("a different environment must not open the same ciphertext")
}
}
func TestOpenRejectsTruncatedAndRotatedKey(t *testing.T) {
key := bytes.Repeat([]byte{0x11}, KeySize)
sealed, err := Seal(key, "secret", AAD("qa-ai", "tenant", 1))
if err != nil {
t.Fatalf("Seal() error = %v", err)
}
if _, err := Open(key, sealed[:4], AAD("qa-ai", "tenant", 1)); err == nil {
t.Fatal("truncated ciphertext must not open")
}
rotated := bytes.Repeat([]byte{0x22}, KeySize)
if _, err := Open(rotated, sealed, AAD("qa-ai", "tenant", 1)); err == nil {
t.Fatal("a rotated master key must not open old ciphertext")
}
}
func TestLoadKeyFileRequirements(t *testing.T) {
good := writeKey(t, bytes.Repeat([]byte{0x01}, KeySize), 0o600)
if _, err := LoadKeyFile(good); err != nil {
t.Fatalf("LoadKeyFile(0600, 32B) error = %v", err)
}
cases := map[string]string{
"missing": "",
"short": writeKey(t, bytes.Repeat([]byte{0x01}, 16), 0o600),
"group-visible": writeKey(t, bytes.Repeat([]byte{0x01}, KeySize), 0o640),
}
for name, path := range cases {
if _, err := LoadKeyFile(path); err != ErrUnavailable {
t.Fatalf("%s: LoadKeyFile() error = %v, want ErrUnavailable", name, err)
}
}
}
+12 -1
View File
@@ -13,6 +13,17 @@ import (
// the operator to paste an id. A missing endpoint or credential is an error the
// caller reports honestly rather than a silently empty picker.
func (verifier *Verifier) ListProductionKnowledgeBases(ctx context.Context, baseURL string) ([]weknora.KnowledgeBase, error) {
// The admin-managed connection wins: the page is where operators record the
// endpoint and key, and a second (file) source would silently disagree.
if verifier.config.ConnectionResolver != nil {
if endpoint, apiKey, ok := verifier.config.ConnectionResolver.Resolve(ctx, "production"); ok {
client, err := verifier.clientWithPolicy(endpoint, apiKey, verifier.config.ProductionAllowDockerHTTP, verifier.config.ProductionAllowPrivateHTTP)
if err != nil {
return nil, err
}
return client.ListKnowledgeBases(ctx)
}
}
resolved := firstNonEmpty(baseURL, verifier.config.ProductionBaseURLFallback)
if resolved == "" {
return nil, errors.New("production WeKnora endpoint is not configured")
@@ -21,7 +32,7 @@ func (verifier *Verifier) ListProductionKnowledgeBases(ctx context.Context, base
if apiKey == "" {
return nil, errors.New("production WeKnora API key file is not available")
}
client, err := verifier.client(resolved, apiKey, verifier.config.ProductionAllowDockerHTTP)
client, err := verifier.clientWithPolicy(resolved, apiKey, verifier.config.ProductionAllowDockerHTTP, verifier.config.ProductionAllowPrivateHTTP)
if err != nil {
return nil, err
}
+35 -11
View File
@@ -40,8 +40,19 @@ type Config struct {
ProductionBaseURLFallback string
TestAllowDockerHTTP bool
ProductionAllowDockerHTTP bool
Timeout time.Duration
Now func() time.Time
// ProductionAllowPrivateHTTP mirrors WEKNORA_ALLOW_PRIVATE_HTTP: the
// production instance is reachable only as a same-LAN http endpoint.
ProductionAllowPrivateHTTP bool
TestAllowPrivateHTTP bool
// ConnectionResolver reads the admin-managed connection (endpoint + key)
// from the governance database. When it answers, it wins over the env
// defaults and over the credential file — the page is the place operators
// configure these, and a second source would drift.
ConnectionResolver interface {
Resolve(ctx context.Context, environment string) (string, string, bool)
}
Timeout time.Duration
Now func() time.Time
}
// Verifier asks endpoints what they really hold. It is safe for concurrent use.
@@ -75,12 +86,20 @@ func (verifier *Verifier) VerifyServiceTarget(ctx context.Context, target govern
testBaseURL := firstNonEmpty(target.TestBaseURL, verifier.config.TestBaseURLFallback)
productionKey := verifier.apiKey(verifier.config.ProductionAPIKeyFile)
testKey := verifier.apiKey(verifier.config.TestAPIKeyFile)
if verifier.config.ConnectionResolver != nil {
if endpoint, key, ok := verifier.config.ConnectionResolver.Resolve(ctx, "test"); ok {
testBaseURL, testKey = endpoint, key
}
if endpoint, key, ok := verifier.config.ConnectionResolver.Resolve(ctx, "production"); ok {
productionBaseURL, productionKey = endpoint, key
}
}
verification := governance.ServiceTargetVerification{
Status: governance.ServiceTargetNotConfigured,
Message: "未配置:两项 ID 都留空,没有可核验的值",
TestEndpoint: verifier.probeEndpoint(ctx, testBaseURL, testKey, "测试地址", verifier.config.TestAllowDockerHTTP),
ProductionEndpoint: verifier.probeEndpoint(ctx, productionBaseURL, productionKey, "生产地址", verifier.config.ProductionAllowDockerHTTP),
TestEndpoint: verifier.probeEndpointWithPolicy(ctx, testBaseURL, testKey, "测试地址", verifier.config.TestAllowDockerHTTP, verifier.config.TestAllowPrivateHTTP),
ProductionEndpoint: verifier.probeEndpointWithPolicy(ctx, productionBaseURL, productionKey, "生产地址", verifier.config.ProductionAllowDockerHTTP, verifier.config.ProductionAllowPrivateHTTP),
CheckedAt: verifier.config.Now().UTC(),
}
if target.ProductionKnowledgeBaseID == "" && target.ProductionTenantID == "" {
@@ -96,7 +115,7 @@ func (verifier *Verifier) VerifyServiceTarget(ctx context.Context, target govern
verification.Message = "未核验:没有可用的生产 API Key 文件(PRODUCTION_WEKNORA_API_KEY_FILE),保存未被阻断"
return verification
}
client, err := verifier.client(productionBaseURL, productionKey, verifier.config.ProductionAllowDockerHTTP)
client, err := verifier.clientWithPolicy(productionBaseURL, productionKey, verifier.config.ProductionAllowDockerHTTP, verifier.config.ProductionAllowPrivateHTTP)
if err != nil {
verification.Status = governance.ServiceTargetCannotVerify
verification.Message = "未核验:生产地址不能作为 WeKnora 端点(" + err.Error() + "),保存未被阻断"
@@ -198,11 +217,15 @@ func (verifier *Verifier) verifyTenantOnly(ctx context.Context, client *weknora.
// is available, otherwise a plain /health liveness call. Advisory — the caller
// only reports it.
func (verifier *Verifier) probeEndpoint(ctx context.Context, baseURL, apiKey, label string, allowDockerHTTP bool) governance.ServiceEndpointStatus {
return verifier.probeEndpointWithPolicy(ctx, baseURL, apiKey, label, allowDockerHTTP, false)
}
func (verifier *Verifier) probeEndpointWithPolicy(ctx context.Context, baseURL, apiKey, label string, allowDockerHTTP, allowPrivateHTTP bool) governance.ServiceEndpointStatus {
if strings.TrimSpace(baseURL) == "" {
return governance.ServiceEndpointStatus{Status: governance.ServiceEndpointNotConfigured, Message: label + "未配置"}
}
if apiKey != "" {
if client, err := verifier.client(baseURL, apiKey, allowDockerHTTP); err == nil {
if client, err := verifier.clientWithPolicy(baseURL, apiKey, allowDockerHTTP, allowPrivateHTTP); err == nil {
bases, listErr := client.ListKnowledgeBases(ctx)
switch {
case listErr == nil:
@@ -271,12 +294,13 @@ func (verifier *Verifier) candidateSuffix(ctx context.Context, client *weknora.C
return fmt.Sprintf(";该地址现有 %d 个知识库:%s", len(bases), strings.Join(listed, "、"))
}
func (verifier *Verifier) client(baseURL, apiKey string, allowDockerHTTP bool) (*weknora.Client, error) {
func (verifier *Verifier) clientWithPolicy(baseURL, apiKey string, allowDockerHTTP, allowPrivateHTTP bool) (*weknora.Client, error) {
return weknora.NewClient(weknora.ClientConfig{
BaseURL: baseURL,
APIKey: apiKey,
Timeout: verifier.config.Timeout,
AllowDockerHTTP: allowDockerHTTP,
BaseURL: baseURL,
APIKey: apiKey,
Timeout: verifier.config.Timeout,
AllowDockerHTTP: allowDockerHTTP,
AllowPrivateHTTP: allowPrivateHTTP,
})
}
+454
View File
@@ -0,0 +1,454 @@
// Package weknoraconn owns the two WeKnora connections the console configures:
// endpoint + write-only API key per environment, with a real listing as the only
// proof a configuration is usable.
//
// It deliberately stores no knowledge-base binding. Which base receives 对内 /
// 对外 content stays in routing_kb_bindings / production_kb_bindings, because one
// meaning may only have one home.
package weknoraconn
import (
"context"
"crypto/sha256"
"encoding/hex"
"errors"
"strconv"
"strings"
"time"
postgresstore "knowledge-governance/internal/platform/postgres"
"knowledge-governance/internal/platform/weknora"
"knowledge-governance/internal/sealedsecret"
)
const (
EnvironmentTest = "test"
EnvironmentProduction = "production"
KeyActionKeep = "keep"
KeyActionReplace = "replace"
KeyActionClear = "clear"
// Outcome vocabulary shared by the API, the stored evidence and the page.
OutcomeOK = "ok"
OutcomeUnreachable = "unreachable"
OutcomeKeyInvalid = "key_invalid"
OutcomeKeyForbidden = "key_forbidden"
// VerificationNotConfigured means there is nothing to verify yet.
VerificationNotConfigured = "not_configured"
// proofTTL bounds how long a successful 测试连接 vouches for a candidate.
proofTTL = 15 * time.Minute
)
var (
ErrInvalid = errors.New("weknora connection request is invalid")
ErrNotFound = errors.New("unknown weknora environment")
ErrStaleRevision = errors.New("weknora connection revision is stale")
ErrNotTested = errors.New("weknora connection must be tested before saving")
ErrStorageUnavailable = errors.New("weknora connection secret storage is unavailable")
)
// Store is the persistence the service needs. The postgres store implements it.
type Store interface {
LoadWeKnoraConnection(ctx context.Context, environment string) (postgresstore.WeKnoraConnection, bool, error)
LoadWeKnoraConnections(ctx context.Context) ([]postgresstore.WeKnoraConnection, error)
SaveWeKnoraConnection(ctx context.Context, connection postgresstore.WeKnoraConnection, now time.Time) error
SaveWeKnoraConnectionTest(ctx context.Context, result postgresstore.WeKnoraConnectionTest, now time.Time) error
LoadWeKnoraConnectionTest(ctx context.Context, environment string) (postgresstore.WeKnoraConnectionTest, bool, error)
UpdateWeKnoraConnectionVerification(ctx context.Context, environment, verification string, libraryCount int, checkedAt time.Time, now time.Time) error
}
// KnowledgeBaseLister is the narrow client the service needs; tests inject it.
type KnowledgeBaseLister interface {
ListKnowledgeBases(ctx context.Context) ([]weknora.KnowledgeBase, error)
}
type Config struct {
// MasterKeyFile is the 0600 32-byte master key. Empty or unreadable means
// the page can read state but cannot store a key — reported, never faked.
MasterKeyFile string
// AllowPrivateHTTP follows WEKNORA_ALLOW_PRIVATE_HTTP: same-LAN plain http
// is usable, public http is not.
AllowPrivateHTTP bool
Timeout time.Duration
Now func() time.Time
// NewLister is overridable in tests. Production leaves it nil.
NewLister func(endpoint, apiKey string) (KnowledgeBaseLister, error)
}
type Service struct {
store Store
config Config
}
func New(store Store, config Config) *Service {
if config.Timeout <= 0 {
config.Timeout = 10 * time.Second
}
if config.Now == nil {
config.Now = time.Now
}
return &Service{store: store, config: config}
}
// View is the page projection. It never carries the key or the ciphertext.
type View struct {
Environment string `json:"environment"`
Endpoint string `json:"endpoint"`
KeyConfigured bool `json:"key_configured"`
KeyTail string `json:"key_tail"`
Verification string `json:"verification"`
LibraryCount int `json:"library_count"`
CheckedAt *time.Time `json:"checked_at"`
UpdatedBy string `json:"updated_by"`
Revision int64 `json:"revision"`
StorageReady bool `json:"storage_ready"`
}
// TestInput is one 测试连接 request. An empty endpoint means "the saved one"; an
// empty key_action means keep.
type TestInput struct {
Endpoint string `json:"endpoint"`
APIKey string `json:"api_key"`
KeyAction string `json:"key_action"`
}
type TestResult struct {
Environment string `json:"environment"`
Endpoint string `json:"endpoint"`
Outcome string `json:"outcome"`
LibraryCount int `json:"library_count"`
Message string `json:"message"`
CheckedAt time.Time `json:"checked_at"`
}
type SaveInput struct {
Endpoint string `json:"endpoint"`
APIKey string `json:"api_key"`
KeyAction string `json:"key_action"`
BaseRevision int64 `json:"base_revision"`
}
func ValidEnvironment(value string) bool {
return value == EnvironmentTest || value == EnvironmentProduction
}
// View reads both environments, or one when environment is non-empty. A missing
// row is projected as 未配置 so the page has a stable shape.
func (service *Service) View(ctx context.Context, environment string) ([]View, error) {
stored, err := service.store.LoadWeKnoraConnections(ctx)
if err != nil {
return nil, err
}
byEnvironment := make(map[string]postgresstore.WeKnoraConnection, len(stored))
for _, connection := range stored {
byEnvironment[connection.Environment] = connection
}
environments := []string{EnvironmentTest, EnvironmentProduction}
if environment != "" {
if !ValidEnvironment(environment) {
return nil, ErrNotFound
}
environments = []string{environment}
}
_, masterKeyErr := sealedsecret.LoadKeyFile(service.config.MasterKeyFile)
views := make([]View, 0, len(environments))
for _, name := range environments {
connection := byEnvironment[name]
verification := connection.Verification
if verification == "" {
verification = VerificationNotConfigured
}
views = append(views, View{
Environment: name,
Endpoint: connection.Endpoint,
KeyConfigured: len(connection.KeyCiphertext) > 0,
KeyTail: connection.KeyTail,
Verification: verification,
LibraryCount: connection.LibraryCount,
CheckedAt: connection.CheckedAt,
UpdatedBy: connection.UpdatedBy,
Revision: connection.Revision,
StorageReady: masterKeyErr == nil,
})
}
return views, nil
}
// Test performs the real GET /api/v1/knowledge-bases against the candidate
// endpoint and key, and records the outcome as the evidence a later save needs.
func (service *Service) Test(ctx context.Context, environment string, input TestInput) (TestResult, error) {
if !ValidEnvironment(environment) {
return TestResult{}, ErrNotFound
}
saved, exists, err := service.store.LoadWeKnoraConnection(ctx, environment)
if err != nil {
return TestResult{}, err
}
endpoint := strings.TrimSpace(input.Endpoint)
if endpoint == "" && exists {
endpoint = saved.Endpoint
}
if endpoint == "" {
return TestResult{}, ErrInvalid
}
action := normalizeKeyAction(input.KeyAction)
apiKey, err := service.candidateKey(saved, exists, action, input.APIKey)
if err != nil {
return TestResult{}, err
}
now := service.config.Now().UTC()
result := TestResult{Environment: environment, Endpoint: endpoint, CheckedAt: now}
if !weknora.HTTPAllowed(endpoint, weknora.HTTPPolicy{AllowPrivateHTTP: service.config.AllowPrivateHTTP}) {
result.Outcome = OutcomeUnreachable
result.Message = "地址不可达:只接受 https,或已放行的私网/回环 http 地址"
_ = service.recordTest(ctx, result, apiKey)
return result, nil
}
lister, err := service.newLister(endpoint, apiKey)
if err != nil {
result.Outcome = OutcomeUnreachable
result.Message = "地址不可达:" + err.Error()
_ = service.recordTest(ctx, result, apiKey)
return result, nil
}
probeCtx, cancel := context.WithTimeout(ctx, service.config.Timeout)
defer cancel()
bases, listErr := lister.ListKnowledgeBases(probeCtx)
if listErr != nil {
result.Outcome, result.Message = classifyListError(listErr)
_ = service.recordTest(ctx, result, apiKey)
return result, nil
}
result.Outcome = OutcomeOK
result.LibraryCount = len(bases)
result.Message = "接口可达 · 已读到 " + strconv.Itoa(len(bases)) + " 个知识库"
if recordErr := service.recordTest(ctx, result, apiKey); recordErr != nil {
// The listing worked but the proof did not land: say so now, because the
// save gate will refuse this configuration a moment later.
result.Message += "(测试证据未能落库,保存会被拒绝,请重试)"
}
// The card may only claim 「可达」 for the configuration it actually probed.
if exists && action != KeyActionReplace && endpoint == saved.Endpoint {
_ = service.store.UpdateWeKnoraConnectionVerification(ctx, environment, result.Outcome, result.LibraryCount, result.CheckedAt, now)
}
return result, nil
}
// Save stores a tested configuration. A new key or a new endpoint must have a
// successful test behind it; keeping a tested configuration is not blocked by a
// jittery endpoint.
func (service *Service) Save(ctx context.Context, environment string, input SaveInput, actor string) (View, error) {
if !ValidEnvironment(environment) {
return View{}, ErrNotFound
}
saved, exists, err := service.store.LoadWeKnoraConnection(ctx, environment)
if err != nil {
return View{}, err
}
endpoint := strings.TrimSpace(input.Endpoint)
if endpoint == "" {
return View{}, ErrInvalid
}
action := normalizeKeyAction(input.KeyAction)
if exists && input.BaseRevision != saved.Revision {
return View{}, ErrStaleRevision
}
if exists && endpoint != saved.Endpoint && action != KeyActionReplace {
return View{}, ErrInvalid
}
apiKey, err := service.candidateKey(saved, exists, action, input.APIKey)
if err != nil {
return View{}, err
}
now := service.config.Now().UTC()
revision := int64(1)
if exists {
revision = saved.Revision + 1
}
verification := VerificationNotConfigured
libraryCount := 0
var checkedAt *time.Time
if apiKey != "" {
if !weknora.HTTPAllowed(endpoint, weknora.HTTPPolicy{AllowPrivateHTTP: service.config.AllowPrivateHTTP}) {
return View{}, ErrInvalid
}
if !exists || action == KeyActionReplace || endpoint != saved.Endpoint {
proof, found, proofErr := service.store.LoadWeKnoraConnectionTest(ctx, environment)
if proofErr != nil {
return View{}, proofErr
}
if !found || proof.Outcome != OutcomeOK || proof.Endpoint != endpoint ||
proof.KeyFingerprint != fingerprint(apiKey) || now.Sub(proof.CheckedAt) > proofTTL {
return View{}, ErrNotTested
}
libraryCount = proof.LibraryCount
checkedAt = &proof.CheckedAt
} else {
libraryCount = saved.LibraryCount
checkedAt = saved.CheckedAt
}
verification = OutcomeOK
}
sealed := []byte{}
if apiKey != "" {
masterKey, keyErr := sealedsecret.LoadKeyFile(service.config.MasterKeyFile)
if keyErr != nil {
return View{}, ErrStorageUnavailable
}
sealed, err = sealedsecret.Seal(masterKey, apiKey, sealedsecret.AAD("weknora-connection", environment, revision))
if err != nil {
return View{}, ErrStorageUnavailable
}
}
connection := postgresstore.WeKnoraConnection{
Environment: environment,
Revision: revision,
Endpoint: endpoint,
KeyCiphertext: sealed,
KeyTail: keyTail(apiKey),
Verification: verification,
LibraryCount: libraryCount,
CheckedAt: checkedAt,
UpdatedBy: actor,
}
if err := service.store.SaveWeKnoraConnection(ctx, connection, now); err != nil {
return View{}, err
}
views, err := service.View(ctx, environment)
if err != nil {
return View{}, err
}
return views[0], nil
}
// Resolve returns the endpoint and key the platform should use for one
// environment. It is the single source other features read instead of guessing
// from environment variables.
func (service *Service) Resolve(ctx context.Context, environment string) (string, string, bool) {
if !ValidEnvironment(environment) {
return "", "", false
}
saved, exists, err := service.store.LoadWeKnoraConnection(ctx, environment)
if err != nil || !exists || saved.Endpoint == "" || len(saved.KeyCiphertext) == 0 {
return "", "", false
}
masterKey, keyErr := sealedsecret.LoadKeyFile(service.config.MasterKeyFile)
if keyErr != nil {
return "", "", false
}
apiKey, openErr := sealedsecret.Open(masterKey, saved.KeyCiphertext, sealedsecret.AAD("weknora-connection", environment, saved.Revision))
if openErr != nil {
return "", "", false
}
return saved.Endpoint, apiKey, true
}
// HTTPPolicy exposes the endpoint policy the client uses, so a caller that
// builds its own client stays in agreement with the service.
func (service *Service) HTTPPolicy() weknora.HTTPPolicy {
return weknora.HTTPPolicy{AllowPrivateHTTP: service.config.AllowPrivateHTTP}
}
func (service *Service) candidateKey(saved postgresstore.WeKnoraConnection, exists bool, action, inputKey string) (string, error) {
switch action {
case KeyActionClear:
return "", nil
case KeyActionReplace:
trimmed := strings.TrimSpace(inputKey)
if trimmed == "" {
return "", ErrInvalid
}
return trimmed, nil
default:
if !exists || len(saved.KeyCiphertext) == 0 {
return "", ErrInvalid
}
masterKey, err := sealedsecret.LoadKeyFile(service.config.MasterKeyFile)
if err != nil {
return "", ErrStorageUnavailable
}
apiKey, err := sealedsecret.Open(masterKey, saved.KeyCiphertext, sealedsecret.AAD("weknora-connection", saved.Environment, saved.Revision))
if err != nil {
return "", ErrStorageUnavailable
}
return apiKey, nil
}
}
func (service *Service) newLister(endpoint, apiKey string) (KnowledgeBaseLister, error) {
if service.config.NewLister != nil {
return service.config.NewLister(endpoint, apiKey)
}
return weknora.NewClient(weknora.ClientConfig{
BaseURL: endpoint,
APIKey: apiKey,
Timeout: service.config.Timeout,
AllowPrivateHTTP: service.config.AllowPrivateHTTP,
})
}
func (service *Service) recordTest(ctx context.Context, result TestResult, apiKey string) error {
return service.store.SaveWeKnoraConnectionTest(ctx, postgresstore.WeKnoraConnectionTest{
Environment: result.Environment,
Endpoint: result.Endpoint,
KeyFingerprint: fingerprint(apiKey),
Outcome: result.Outcome,
LibraryCount: result.LibraryCount,
Message: result.Message,
}, result.CheckedAt)
}
// classifyListError maps one failed listing onto the four answers the page
// promises, so 「密钥无效」 and 「密钥无权限」 never collapse into one message.
func classifyListError(err error) (string, string) {
var httpErr *weknora.HTTPError
if errors.As(err, &httpErr) {
switch httpErr.StatusCode {
case 401:
return OutcomeKeyInvalid, "密钥无效:该实例拒绝了这把 API Key(401)"
case 403:
return OutcomeKeyForbidden, "密钥无权限读取知识库列表(403)"
}
}
switch {
case errors.Is(err, context.DeadlineExceeded):
return OutcomeUnreachable, "地址不可达:请求超时"
default:
var netErr interface{ Timeout() bool }
if errors.As(err, &netErr) && netErr.Timeout() {
return OutcomeUnreachable, "地址不可达:请求超时"
}
return OutcomeUnreachable, "地址不可达:连接失败"
}
}
func normalizeKeyAction(action string) string {
switch strings.TrimSpace(action) {
case KeyActionReplace:
return KeyActionReplace
case KeyActionClear:
return KeyActionClear
default:
return KeyActionKeep
}
}
func fingerprint(apiKey string) string {
sum := sha256.Sum256([]byte(apiKey))
return hex.EncodeToString(sum[:])
}
// keyTail is the only part of a key the page may show: the last four characters.
func keyTail(apiKey string) string {
if apiKey == "" {
return ""
}
runes := []rune(apiKey)
if len(runes) <= 4 {
return string(runes)
}
return string(runes[len(runes)-4:])
}
+249
View File
@@ -0,0 +1,249 @@
package weknoraconn
import (
"context"
"errors"
"os"
"path/filepath"
"testing"
"time"
"knowledge-governance/internal/platform/postgres"
"knowledge-governance/internal/platform/weknora"
)
type fakeStore struct {
connections map[string]postgres.WeKnoraConnection
tests map[string]postgres.WeKnoraConnectionTest
}
func newFakeStore() *fakeStore {
return &fakeStore{
connections: map[string]postgres.WeKnoraConnection{},
tests: map[string]postgres.WeKnoraConnectionTest{},
}
}
func (store *fakeStore) LoadWeKnoraConnection(_ context.Context, environment string) (postgres.WeKnoraConnection, bool, error) {
connection, ok := store.connections[environment]
return connection, ok, nil
}
func (store *fakeStore) LoadWeKnoraConnections(context.Context) ([]postgres.WeKnoraConnection, error) {
result := make([]postgres.WeKnoraConnection, 0, len(store.connections))
for _, connection := range store.connections {
result = append(result, connection)
}
return result, nil
}
func (store *fakeStore) SaveWeKnoraConnection(_ context.Context, connection postgres.WeKnoraConnection, _ time.Time) error {
store.connections[connection.Environment] = connection
return nil
}
func (store *fakeStore) SaveWeKnoraConnectionTest(_ context.Context, result postgres.WeKnoraConnectionTest, now time.Time) error {
result.CheckedAt = now
store.tests[result.Environment] = result
return nil
}
func (store *fakeStore) LoadWeKnoraConnectionTest(_ context.Context, environment string) (postgres.WeKnoraConnectionTest, bool, error) {
result, ok := store.tests[environment]
return result, ok, nil
}
func (store *fakeStore) UpdateWeKnoraConnectionVerification(_ context.Context, environment, verification string, libraryCount int, checkedAt time.Time, _ time.Time) error {
connection, ok := store.connections[environment]
if !ok {
return nil
}
connection.Verification = verification
connection.LibraryCount = libraryCount
connection.CheckedAt = &checkedAt
store.connections[environment] = connection
return nil
}
type fakeLister struct {
bases []weknora.KnowledgeBase
err error
}
func (lister fakeLister) ListKnowledgeBases(context.Context) ([]weknora.KnowledgeBase, error) {
return lister.bases, lister.err
}
func newService(t *testing.T, store Store, lister fakeLister) *Service {
t.Helper()
path := filepath.Join(t.TempDir(), "master.key")
if err := os.WriteFile(path, []byte("0123456789abcdef0123456789abcdef"), 0o600); err != nil {
t.Fatalf("write master key: %v", err)
}
if err := os.Chmod(path, 0o600); err != nil {
t.Fatalf("chmod master key: %v", err)
}
now := time.Date(2026, 11, 22, 7, 0, 0, 0, time.UTC)
return New(store, Config{
MasterKeyFile: path,
AllowPrivateHTTP: true,
Timeout: time.Second,
Now: func() time.Time { return now },
NewLister: func(endpoint, apiKey string) (KnowledgeBaseLister, error) {
if endpoint == "" || apiKey == "" {
return nil, errors.New("missing endpoint or key")
}
return lister, nil
},
})
}
func TestTestClassifiesTheFourAnswers(t *testing.T) {
cases := []struct {
name string
err error
wantOutcome string
wantMessage string
}{
{"unauthorized", &weknora.HTTPError{StatusCode: 401}, OutcomeKeyInvalid, "密钥无效"},
{"forbidden", &weknora.HTTPError{StatusCode: 403}, OutcomeKeyForbidden, "密钥无权限"},
{"timeout", context.DeadlineExceeded, OutcomeUnreachable, "地址不可达"},
{"refused", errors.New("dial tcp: connection refused"), OutcomeUnreachable, "地址不可达"},
}
for _, testCase := range cases {
service := newService(t, newFakeStore(), fakeLister{err: testCase.err})
result, err := service.Test(context.Background(), EnvironmentTest, TestInput{
Endpoint: "http://127.0.0.1:8092", APIKey: "sk-test-1234", KeyAction: KeyActionReplace,
})
if err != nil {
t.Fatalf("%s: Test() error = %v", testCase.name, err)
}
if result.Outcome != testCase.wantOutcome {
t.Fatalf("%s: outcome = %q, want %q", testCase.name, result.Outcome, testCase.wantOutcome)
}
if !contains(result.Message, testCase.wantMessage) {
t.Fatalf("%s: message = %q, want it to mention %q", testCase.name, result.Message, testCase.wantMessage)
}
}
}
func TestTestSuccessReportsLibraryCount(t *testing.T) {
service := newService(t, newFakeStore(), fakeLister{bases: []weknora.KnowledgeBase{{ID: "a"}, {ID: "b"}, {ID: "c"}}})
result, err := service.Test(context.Background(), EnvironmentProduction, TestInput{
Endpoint: "http://172.29.151.11:18093", APIKey: "prod-key-9999", KeyAction: KeyActionReplace,
})
if err != nil {
t.Fatalf("Test() error = %v", err)
}
if result.Outcome != OutcomeOK || result.LibraryCount != 3 {
t.Fatalf("result = %+v", result)
}
if !contains(result.Message, "3 个知识库") {
t.Fatalf("message = %q", result.Message)
}
}
func TestSaveRequiresTestProofAndProjectsTailOnly(t *testing.T) {
store := newFakeStore()
service := newService(t, store, fakeLister{bases: []weknora.KnowledgeBase{{ID: "a"}, {ID: "b"}}})
ctx := context.Background()
save := SaveInput{Endpoint: "http://127.0.0.1:8092", APIKey: "sk-live-abcd", KeyAction: KeyActionReplace}
if _, err := service.Save(ctx, EnvironmentTest, save, "admin"); !errors.Is(err, ErrNotTested) {
t.Fatalf("Save() without a test = %v, want ErrNotTested", err)
}
if _, err := service.Test(ctx, EnvironmentTest, TestInput{Endpoint: save.Endpoint, APIKey: save.APIKey, KeyAction: KeyActionReplace}); err != nil {
t.Fatalf("Test() error = %v", err)
}
view, err := service.Save(ctx, EnvironmentTest, save, "admin")
if err != nil {
t.Fatalf("Save() error = %v", err)
}
if !view.KeyConfigured || view.KeyTail != "abcd" || view.Verification != OutcomeOK || view.LibraryCount != 2 {
t.Fatalf("view = %+v", view)
}
if view.Revision != 1 {
t.Fatalf("revision = %d", view.Revision)
}
endpoint, apiKey, ok := service.Resolve(ctx, EnvironmentTest)
if !ok || endpoint != save.Endpoint || apiKey != save.APIKey {
t.Fatalf("Resolve() = %q %q %v", endpoint, apiKey, ok)
}
// The proof is bound to the key: another key must not reuse it.
other := SaveInput{Endpoint: save.Endpoint, APIKey: "sk-live-zzzz", KeyAction: KeyActionReplace, BaseRevision: 1}
if _, err := service.Save(ctx, EnvironmentTest, other, "admin"); !errors.Is(err, ErrNotTested) {
t.Fatalf("Save() with a different untested key = %v, want ErrNotTested", err)
}
}
func TestSaveRejectsEndpointChangeWithoutReenteringKey(t *testing.T) {
store := newFakeStore()
service := newService(t, store, fakeLister{bases: []weknora.KnowledgeBase{{ID: "a"}}})
ctx := context.Background()
first := SaveInput{Endpoint: "http://127.0.0.1:8092", APIKey: "sk-live-abcd", KeyAction: KeyActionReplace}
if _, err := service.Test(ctx, EnvironmentTest, TestInput{Endpoint: first.Endpoint, APIKey: first.APIKey, KeyAction: KeyActionReplace}); err != nil {
t.Fatal(err)
}
if _, err := service.Save(ctx, EnvironmentTest, first, "admin"); err != nil {
t.Fatalf("first Save() error = %v", err)
}
if _, err := service.Save(ctx, EnvironmentTest, SaveInput{Endpoint: "http://127.0.0.1:9092", KeyAction: KeyActionKeep, BaseRevision: 1}, "admin"); !errors.Is(err, ErrInvalid) {
t.Fatalf("endpoint change with keep = %v, want ErrInvalid", err)
}
if _, err := service.Save(ctx, EnvironmentTest, SaveInput{Endpoint: "http://127.0.0.1:8092", KeyAction: KeyActionKeep, BaseRevision: 7}, "admin"); !errors.Is(err, ErrStaleRevision) {
t.Fatalf("stale revision = %v, want ErrStaleRevision", err)
}
// Keeping the tested configuration must not be blocked by proof age.
view, err := service.Save(ctx, EnvironmentTest, SaveInput{Endpoint: "http://127.0.0.1:8092", KeyAction: KeyActionKeep, BaseRevision: 1}, "admin")
if err != nil || view.Verification != OutcomeOK || view.KeyTail != "abcd" {
t.Fatalf("keep Save() = %+v, %v", view, err)
}
}
func TestClearKeyResetsVerification(t *testing.T) {
store := newFakeStore()
service := newService(t, store, fakeLister{bases: []weknora.KnowledgeBase{{ID: "a"}}})
ctx := context.Background()
if _, err := service.Test(ctx, EnvironmentProduction, TestInput{Endpoint: "https://prod.example", APIKey: "prod-key", KeyAction: KeyActionReplace}); err != nil {
t.Fatal(err)
}
if _, err := service.Save(ctx, EnvironmentProduction, SaveInput{Endpoint: "https://prod.example", APIKey: "prod-key", KeyAction: KeyActionReplace}, "admin"); err != nil {
t.Fatal(err)
}
view, err := service.Save(ctx, EnvironmentProduction, SaveInput{Endpoint: "https://prod.example", KeyAction: KeyActionClear, BaseRevision: 1}, "admin")
if err != nil {
t.Fatalf("clear Save() error = %v", err)
}
if view.KeyConfigured || view.KeyTail != "" || view.Verification != VerificationNotConfigured {
t.Fatalf("cleared view = %+v", view)
}
if _, _, ok := service.Resolve(ctx, EnvironmentProduction); ok {
t.Fatal("a cleared connection must not resolve")
}
}
func TestPublicHTTPIsRefusedEvenWhenPrivateHTTPIsAllowed(t *testing.T) {
service := newService(t, newFakeStore(), fakeLister{})
result, err := service.Test(context.Background(), EnvironmentTest, TestInput{Endpoint: "http://weknora.example", APIKey: "k", KeyAction: KeyActionReplace})
if err != nil {
t.Fatalf("Test() error = %v", err)
}
if result.Outcome != OutcomeUnreachable {
t.Fatalf("outcome = %q", result.Outcome)
}
if _, err := service.Save(context.Background(), EnvironmentTest, SaveInput{Endpoint: "http://weknora.example", APIKey: "k", KeyAction: KeyActionReplace}, "admin"); err == nil {
t.Fatal("saving a public http endpoint must fail")
}
}
func contains(value, needle string) bool {
return len(needle) == 0 || (len(value) >= len(needle) && indexOf(value, needle) >= 0)
}
func indexOf(value, needle string) int {
for i := 0; i+len(needle) <= len(value); i++ {
if value[i:i+len(needle)] == needle {
return i
}
}
return -1
}
+10 -3
View File
@@ -1,6 +1,7 @@
import { useCallback, useEffect, useState } from 'react'
import { useOptionalAuth } from './auth'
import { WeKnoraConnections } from './WeKnoraConnections'
import { fetchProductionBindingOptions, fetchProductionBindings, saveProductionBindings } from './productionBindings'
import type { ProductionBindings } from './productionBindings'
import type { KnowledgeBaseOption } from './routingBindings'
@@ -41,9 +42,12 @@ export function ProductionBindingsSection() {
const next = await saveProductionBindings({ internal_kb_id: internalDraft, external_kb_id: externalDraft })
setBindings(next)
const where = `对内 ${next.internal_kb_name || next.internal_kb_id.slice(0, 8) || '未绑定'} · 对外 ${next.external_kb_name || next.external_kb_id.slice(0, 8) || '未绑定'}`
const frozen = next.frozen + next.retargetable > 0
? `;已冻结目标 ${next.frozen} 条(不会被改写),仍可改指向 ${next.retargetable} 条`
: ''
setMessage(next.production_connected
? `发布目标已更新:${where}。之后新发布的“对内/对外”内容会写入这两个生产库(已发布过的条目仍回到原目标)。`
: `发布目标已保存:${where};但当前核对不了生产端(${next.production_message}),下次发布前请确认。`)
? `发布目标已更新:${where}${frozen}。之后新发布的“对内/对外”内容会写入这两个生产库。`
: `发布目标已保存:${where}${frozen};但当前核对不了生产端(${next.production_message}),下次发布前请确认。`)
} catch (cause) { setError(cause instanceof Error ? cause.message : '保存生产知识库绑定失败') }
finally { setSaving(false) }
}
@@ -62,11 +66,14 @@ export function ProductionBindingsSection() {
<option value="">{placeholder}</option>
{options.map((base) => <option key={base.id} value={base.id}>{optionLabel(base)}</option>)}
</select>
: <input value={value} onChange={(event) => onChange(event.target.value.trim())} placeholder={`${placeholder}(输入生产知识库 ID)`} aria-label={placeholder} />
: <select value="" disabled aria-label={placeholder}>
<option value="">读不到生产库列表:先在上方把生产连接测通</option>
</select>
)
return <section className="settings-panel wide" id="settings-production-bindings">
<div className="settings-section-heading"><div><h2>生产知识库绑定</h2><p>发布链路的“源库 → 目标库”:新发布的对内 / 对外内容按这里的绑定写入生产 WeKnora 的对应知识库。留空表示未绑定,按同 ID 语义发布。</p></div><button onClick={() => void load()} disabled={loading}>{loading ? '读取中…' : '重新读取'}</button></div>
<WeKnoraConnections environment="production" title="生产 WeKnora" placeholder="http://172.29.151.11:18093" onSaved={() => void load()} />
{error ? <p className="error-message" role="alert">{error}</p> : null}
{bindings ? <div className="kb-binding-grid">
{renderSide('对内生产知识库', bindings.internal_kb_id, bindings.internal_kb_name)}
+148 -43
View File
@@ -1,6 +1,7 @@
import { useCallback, useEffect, useState } from 'react'
import { useOptionalAuth } from './auth'
import { WeKnoraConnections } from './WeKnoraConnections'
import { fetchRoutingBindingOptions, fetchRoutingBindings, saveRoutingBindings } from './routingBindings'
import type { KnowledgeBaseOption, RoutingBindings } from './routingBindings'
@@ -17,67 +18,171 @@ export function RoutingBindingsSection() {
const [message, setMessage] = useState('')
const load = useCallback(async () => {
setLoading(true); setError(null)
setLoading(true)
setError(null)
try {
const next = await fetchRoutingBindings()
setBindings(next)
setInternalDraft(next.internal_bound_by_ui ? next.internal_kb_id : '')
setExternalDraft(next.external_bound_by_ui ? next.external_kb_id : '')
try { setOptions(await fetchRoutingBindingOptions()) } catch { setOptions([]) }
} catch (cause) { setError(cause instanceof Error ? cause.message : '读取测试知识库绑定失败') }
finally { setLoading(false) }
try {
setOptions(await fetchRoutingBindingOptions())
} catch {
setOptions([])
}
} catch (cause) {
setError(cause instanceof Error ? cause.message : '读取测试知识库绑定失败')
} finally {
setLoading(false)
}
}, [])
useEffect(() => { void load() }, [load])
useEffect(() => {
void load()
}, [load])
const dirty = bindings !== null && (internalDraft !== (bindings.internal_bound_by_ui ? bindings.internal_kb_id : '') || externalDraft !== (bindings.external_bound_by_ui ? bindings.external_kb_id : ''))
const dirty =
bindings !== null &&
(internalDraft !== (bindings.internal_bound_by_ui ? bindings.internal_kb_id : '') ||
externalDraft !== (bindings.external_bound_by_ui ? bindings.external_kb_id : ''))
const sameSelection = internalDraft !== '' && internalDraft === externalDraft
const save = async () => {
setSaving(true); setError(null); setMessage('')
setSaving(true)
setError(null)
setMessage('')
try {
const next = await saveRoutingBindings({ internal_kb_id: internalDraft, external_kb_id: externalDraft })
setBindings(next)
const replan = next.replanned || next.retired_duplicates
? `;同时把 ${next.replanned} 项还没上传的待入库重新指向新库${next.retired_duplicates ? `,${next.retired_duplicates} 项因新库里已有同篇而被退休` : ''}`
: ''
setMessage(`绑定已生效:对内 ${next.internal_kb_name || next.internal_kb_id.slice(0, 8) || '未绑定'} · 对外 ${next.external_kb_name || next.external_kb_id.slice(0, 8) || '未绑定'}。此后“来源与目录”的标记按新绑定路由${replan}。`)
} catch (cause) { setError(cause instanceof Error ? cause.message : '保存测试知识库绑定失败') }
finally { setSaving(false) }
const replan =
next.replanned || next.retired_duplicates
? `;同时把 ${next.replanned} 项还没上传的待入库重新指向新库${next.retired_duplicates ? `,${next.retired_duplicates} 项因新库里已有同篇而被退休` : ''}`
: ''
const fallbacks: string[] = []
if (!next.internal_bound_by_ui)
fallbacks.push(
`对内回退到部署默认库 ${next.internal_fallback_kb_id ? `${next.internal_fallback_kb_id.slice(0, 8)}…` : '(未设置)'}`
)
if (!next.external_bound_by_ui)
fallbacks.push(
`对外回退到部署默认库 ${next.external_fallback_kb_id ? `${next.external_fallback_kb_id.slice(0, 8)}…` : '(未设置)'}`
)
setMessage(
`绑定已生效:对内 ${next.internal_kb_name || next.internal_kb_id.slice(0, 8) || '未绑定'} · 对外 ${next.external_kb_name || next.external_kb_id.slice(0, 8) || '未绑定'}${fallbacks.length ? `;${fallbacks.join(';')}` : ''}。此后“来源与目录”的标记按新绑定路由${replan}。`
)
} catch (cause) {
setError(cause instanceof Error ? cause.message : '保存测试知识库绑定失败')
} finally {
setSaving(false)
}
}
const optionLabel = (base: KnowledgeBaseOption) => `${base.name}(${base.knowledge_count} 文档 · ${base.id.slice(0, 8)}…)`
const renderSide = (label: string, boundID: string, boundName: string, fromEnv: boolean, boundByUI: boolean) => (
const optionLabel = (base: KnowledgeBaseOption) =>
`${base.name}(${base.knowledge_count} 文档 · ${base.id.slice(0, 8)}…)`
const renderSide = (
label: string,
boundID: string,
boundName: string,
fromEnv: boolean,
boundByUI: boolean,
fallbackID = ''
) => (
<div className={`kb-binding-side ${boundID ? 'bound' : 'warn'}`}>
<b>{label}</b>
<span>{boundID ? (boundName || `${boundID.slice(0, 8)}…`) : '未绑定 · 该方向的标记会被拒绝'}</span>
<small>{boundID ? (boundByUI ? (boundName ? `UI 绑定 · ${boundID.slice(0, 8)}…` : 'UI 绑定') : fromEnv ? '来自部署默认值(env)' : '') : '请绑定一个测试知识库'}</small>
<span>{boundID ? boundName || `${boundID.slice(0, 8)}…` : '未绑定 · 该方向的标记会被拒绝'}</span>
<small>
{boundID
? boundByUI
? boundName
? `UI 绑定 · ${boundID.slice(0, 8)}…`
: 'UI 绑定'
: fromEnv
? `回退到部署默认库 ${fallbackID ? `${fallbackID.slice(0, 8)}…` : '(未设置)'}`
: ''
: '请绑定一个测试知识库'}
</small>
</div>
)
const editorFor = (value: string, onChange: (next: string) => void, placeholder: string) => (
options.length > 0
? <select value={value} onChange={(event) => onChange(event.target.value)} aria-label={placeholder}>
<option value="">{placeholder}</option>
{options.map((base) => <option key={base.id} value={base.id}>{optionLabel(base)}</option>)}
</select>
: <input value={value} onChange={(event) => onChange(event.target.value.trim())} placeholder={`${placeholder}(输入知识库 ID)`} aria-label={placeholder} />
)
const editorFor = (value: string, onChange: (next: string) => void, placeholder: string) =>
options.length > 0 ? (
<select value={value} onChange={(event) => onChange(event.target.value)} aria-label={placeholder}>
<option value="">{placeholder}</option>
{options.map((base) => (
<option key={base.id} value={base.id}>
{optionLabel(base)}
</option>
))}
</select>
) : (
<select value="" disabled aria-label={placeholder}>
<option value="">读不到测试库列表:先在上方把测试连接测通</option>
</select>
)
return <section className="settings-panel wide" id="settings-routing-bindings">
<div className="settings-section-heading"><div><h2>测试知识库绑定</h2><p>“来源与目录”里的对内 / 对外标记按这里的绑定分发到对应的测试 WeKnora 知识库;保存后立即生效,无需重启。发布写入的生产知识库见「生产知识库绑定」。</p></div><button onClick={() => void load()} disabled={loading}>{loading ? '读取中…' : '重新读取'}</button></div>
{error ? <p className="error-message" role="alert">{error}</p> : null}
{bindings ? <div className="kb-binding-grid">
{renderSide('对内知识库', bindings.internal_kb_id, bindings.internal_kb_name, bindings.internal_env_fallback, bindings.internal_bound_by_ui)}
{renderSide('对外知识库', bindings.external_kb_id, bindings.external_kb_name, bindings.external_env_fallback, bindings.external_bound_by_ui)}
</div> : null}
{bindings && !bindings.weknora_connected ? <p className="hint">当前读不到 WeKnora 的库列表,只能按 ID 填写;连接恢复后可改为下拉选择。</p> : null}
{isAdmin && bindings ? <div className="kb-binding-editor">
<label>对内绑定 {editorFor(internalDraft, setInternalDraft, '选择对内知识库')}</label>
<label>对外绑定 {editorFor(externalDraft, setExternalDraft, '选择对外知识库')}</label>
<p className="hint">留空 = 取消 UI 绑定,回退到部署默认值;对内与对外必须是不同的库。</p>
{sameSelection ? <p className="error-message">对内与对外必须绑定不同的知识库</p> : null}
<button onClick={() => void save()} disabled={saving || !dirty || sameSelection}>{saving ? '正在校验并保存…' : '保存绑定'}</button>
{message ? <p className="success-message" role="status">{message}</p> : null}
</div> : null}
{!isAdmin ? <p className="hint">仅管理员可修改测试知识库绑定。</p> : null}
</section>
return (
<section className="settings-panel wide" id="settings-routing-bindings">
<div className="settings-section-heading">
<div>
<h2>测试知识库绑定</h2>
<p>
“来源与目录”里的对内 / 对外标记按这里的绑定分发到对应的测试 WeKnora
知识库;保存后立即生效,无需重启。发布写入的生产知识库见「生产知识库绑定」。
</p>
</div>
<button onClick={() => void load()} disabled={loading}>
{loading ? '读取中…' : '重新读取'}
</button>
</div>
<WeKnoraConnections
environment="test"
title="测试 WeKnora"
placeholder="http://127.0.0.1:8092"
onSaved={() => void load()}
/>
{error ? (
<p className="error-message" role="alert">
{error}
</p>
) : null}
{bindings ? (
<div className="kb-binding-grid">
{renderSide(
'对内知识库',
bindings.internal_kb_id,
bindings.internal_kb_name,
bindings.internal_env_fallback,
bindings.internal_bound_by_ui,
bindings.internal_fallback_kb_id
)}
{renderSide(
'对外知识库',
bindings.external_kb_id,
bindings.external_kb_name,
bindings.external_env_fallback,
bindings.external_bound_by_ui,
bindings.external_fallback_kb_id
)}
</div>
) : null}
{bindings && !bindings.weknora_connected ? (
<p className="hint">当前读不到 WeKnora 的库列表:先在上面的连接卡把地址与密钥配好并测通,再回来选库。</p>
) : null}
{isAdmin && bindings ? (
<div className="kb-binding-editor">
<label>对内绑定 {editorFor(internalDraft, setInternalDraft, '选择对内知识库')}</label>
<label>对外绑定 {editorFor(externalDraft, setExternalDraft, '选择对外知识库')}</label>
<p className="hint">留空 = 取消 UI 绑定,回退到部署默认值;对内与对外必须是不同的库。</p>
{sameSelection ? <p className="error-message">对内与对外必须绑定不同的知识库</p> : null}
<button onClick={() => void save()} disabled={saving || !dirty || sameSelection}>
{saving ? '正在校验并保存…' : '保存绑定'}
</button>
{message ? (
<p className="success-message" role="status">
{message}
</p>
) : null}
</div>
) : null}
{!isAdmin ? <p className="hint">仅管理员可修改测试知识库绑定。</p> : null}
</section>
)
}
+5 -3
View File
@@ -424,12 +424,14 @@ describe('SystemSettingsView', () => {
expect(on).toContain('测试 WeKnora')
expect(on).toContain('可达 · 可接单')
expect(on).toContain('延迟 86ms')
expect(on).toContain('已启用 · 可提交生产请求')
expect(on).toContain('生产写入:开启 · 可提交生产请求')
expect(on).toContain('生产写入:开启')
expect(on).toContain('发布目标与凭据:管理员受限配置')
const off = view(false, false)
expect(off).toContain('未启用')
// 连接状态与生产写入是两行:闸门关掉不代表「连接不可达」,两个事实分开说。
expect(off).toContain('连接:可达')
expect(off).toContain('生产写入:关闭')
expect(off).not.toContain('被阻断')
// 卡片状态由真实探测/门禁驱动,写死的“已连接 / 未连接 / 生产映射:未配置”必须消失。
for (const removed of ['本地真实连接', '生产映射:未配置']) expect(off).not.toContain(removed)
// 生产端点可达性来自真实探活,且只说真话:探活不等于验证过接单能力。
@@ -453,7 +455,7 @@ describe('SystemSettingsView', () => {
initialSection="services"
/>
)
expect(blocked).toContain('已启用 · 被阻断')
expect(blocked).toContain('生产写入:开启 · 恢复演练未核验')
// 未配置生产端点时必须显式说「未配置」,不得靠文案含糊过去。
expect(blocked).toContain('端点探测:暂无真实探测结果')
const unconfigured = renderToStaticMarkup(
+23 -26
View File
@@ -119,6 +119,15 @@ export const productionWeKnoraProbe = (monitor: MonitorOverview | null): string
return `端点探测:${label}${detail ? `(${detail})` : ''}`
}
// 生产卡片拆两行:连接是否可达,与生产写入是否开启是两件事 —— 以前把
// 「被阻断」混进连接状态,页面会自相矛盾(端点明明可达却显示被阻断)。
const productionConnectionLine = (monitor: MonitorOverview | null): string => {
const health = findHealth(monitor, '生产 WeKnora')
if (!health) return '连接:暂无探测结果'
if (!health.configured) return '连接:未配置'
return health.liveness === 'up' ? '连接:可达' : '连接:不可达'
}
export function SystemSettingsView({
sources,
connections,
@@ -199,6 +208,12 @@ export function SystemSettingsView({
setDirty(false)
onSave(candidateInput())
}
const productionConnectionLineText = productionConnectionLine(monitor)
const productionWriteLine = !productionEnabled
? '生产写入:关闭'
: productionBackupRestoreVerified
? '生产写入:开启 · 可提交生产请求'
: '生产写入:开启 · 恢复演练未核验'
return (
<main className="page-shell system-settings">
<header className="hero compact">
@@ -278,14 +293,8 @@ export function SystemSettingsView({
</article>
<article className="production">
<b>生产 WeKnora</b>
<span>
{!productionEnabled
? '未启用'
: productionBackupRestoreVerified
? '已启用 · 可提交生产请求'
: '已启用 · 被阻断'}
</span>
<small>{`${productionWeKnoraProbe(monitor)};生产写入:${productionEnabled ? '开启' : '关闭'};发布目标与凭据:管理员受限配置,本页不可回读`}</small>
<span>{productionConnectionLineText}</span>
<small>{`${productionWeKnoraProbe(monitor)};${productionWriteLine};发布目标与凭据:管理员受限配置,本页不可回读`}</small>
</article>
</div>
<div className="safe-setting-grid production-endpoint-form">
@@ -293,27 +302,11 @@ export function SystemSettingsView({
<>
<label>
测试地址
<input
value={testEndpoint}
onChange={(event) => {
setTestEndpoint(event.target.value)
setDirty(true)
}}
placeholder="https://weknora.test.example"
aria-invalid={!testEndpointValid}
/>
<input value={testEndpoint || '未配置'} readOnly disabled />
</label>
<label>
生产地址
<input
value={endpoint}
onChange={(event) => {
setEndpoint(event.target.value)
setDirty(true)
}}
placeholder="https://weknora.prod.example"
aria-invalid={!endpointValid}
/>
<input value={endpoint || '未配置'} readOnly disabled />
</label>
<label>
生产 ID
@@ -376,6 +369,10 @@ export function SystemSettingsView({
原子切换);后端同时对测试地址/生产地址做真实探活,并用生产地址真查这两个 ID(WeKnora
列库接口):端点回答"没有这个知识库"或租户不符会拒绝保存,端点抖动、鉴权失败或未配置生产凭据只警告不拦,核验原话与知识库名在保存后显示。
</small>
<p className="hint">
地址已移到「测试知识库绑定 /
生产知识库绑定」分区顶部的连接卡维护(可在那里测试连接);这里是回退值,只读。
</p>
{serviceSettingsValid ? null : (
<p className="error-message" role="alert">
格式不合法:地址需 http:// 或 https:// 开头的纯地址,不能带用户名密码、? 查询串或 # 片段;生产
+183
View File
@@ -0,0 +1,183 @@
import { useCallback, useEffect, useState } from 'react'
import { PasswordInput } from './PasswordInput'
import { useOptionalAuth } from './auth'
import {
fetchWeKnoraConnections,
keyLabel,
saveWeKnoraConnection,
testWeKnoraConnection,
verificationLabel,
} from './weknoraConnections'
import type { WeKnoraConnection, WeKnoraEnvironment } from './weknoraConnections'
interface Props {
environment: WeKnoraEnvironment
title: string
placeholder: string
onSaved?: () => void
}
// 连接卡:地址 + 写-only 密钥 + 真实列库测试。它只改「连哪台实例、用哪把钥匙」,
// 不碰绑定,也不触发任何同步或发布。
export function WeKnoraConnections({ environment, title, placeholder, onSaved }: Props) {
const auth = useOptionalAuth()
const isAdmin = auth?.identity?.role === 'admin'
const [connection, setConnection] = useState<WeKnoraConnection | null>(null)
const [endpointDraft, setEndpointDraft] = useState('')
const [keyDraft, setKeyDraft] = useState('')
const [testing, setTesting] = useState(false)
const [saving, setSaving] = useState(false)
const [error, setError] = useState<string | null>(null)
const [message, setMessage] = useState('')
const [testedEndpoint, setTestedEndpoint] = useState('')
const load = useCallback(async () => {
try {
const all = await fetchWeKnoraConnections()
const found = all.find((item) => item.environment === environment) ?? null
setConnection(found)
setEndpointDraft(found?.endpoint ?? '')
} catch (cause) {
setError(cause instanceof Error ? cause.message : '读取连接失败')
}
}, [environment])
useEffect(() => {
void load()
}, [load])
const endpoint = endpointDraft.trim()
const keyEntered = keyDraft.trim() !== ''
const endpointChanged = connection !== null && endpoint !== connection.endpoint
const canTest = endpoint !== '' && !testing && !saving
const tested = testedEndpoint !== '' && testedEndpoint === endpoint
const canSave = endpoint !== '' && !saving && !testing && (keyEntered || endpointChanged ? tested : true)
const test = async () => {
setTesting(true)
setError(null)
setMessage('')
try {
const result = await testWeKnoraConnection(environment, {
endpoint,
...(keyEntered
? { api_key: keyDraft.trim(), key_action: 'replace' as const }
: { key_action: 'keep' as const }),
})
setMessage(result.message)
setTestedEndpoint(result.outcome === 'ok' ? endpoint : '')
if (result.outcome !== 'ok') setError(result.message)
} catch (cause) {
setError(cause instanceof Error ? cause.message : '测试连接失败')
} finally {
setTesting(false)
}
}
const save = async (action: 'keep' | 'replace' | 'clear') => {
setSaving(true)
setError(null)
try {
const next = await saveWeKnoraConnection(environment, {
endpoint,
...(action === 'replace' ? { api_key: keyDraft.trim() } : {}),
key_action: action,
base_revision: connection?.revision ?? 0,
})
setConnection(next)
setEndpointDraft(next.endpoint)
setKeyDraft('')
setTestedEndpoint('')
setMessage(`已保存:${keyLabel(next)};最近一次测试:${verificationLabel(next)}。保存未触发任何同步或发布。`)
onSaved?.()
} catch (cause) {
setError(cause instanceof Error ? cause.message : '保存连接失败')
} finally {
setSaving(false)
}
}
const clearKey = () => {
if (!window.confirm('清除后该侧将没有任何可用密钥,发布与列库都会失败。确定清除?')) return
void save('clear')
}
const saveAction = keyEntered ? 'replace' : 'keep'
return (
<div className="weknora-connection-card" id={`settings-weknora-connection-${environment}`}>
<div className="kb-binding-grid">
<div className={`kb-binding-side ${connection?.verification === 'ok' ? 'bound' : 'warn'}`}>
<b>{title}</b>
<span>连接:{verificationLabel(connection)}</span>
<small>
{connection?.endpoint
? `地址:${connection.endpoint} · 密钥:${keyLabel(connection)}`
: '还没有配置地址与密钥'}
</small>
</div>
</div>
{connection && !connection.storage_ready ? (
<p className="hint">密钥存储不可用(主密钥文件缺失或权限不是 0600):可以读取当前状态,但保存会被拒绝。</p>
) : null}
{isAdmin ? (
<div className="kb-binding-editor">
<label>
{title}地址
<input
value={endpointDraft}
onChange={(event) => {
setEndpointDraft(event.target.value)
setTestedEndpoint('')
}}
placeholder={placeholder}
aria-label={`${title}地址`}
/>
</label>
<label>
API Key
<PasswordInput
autoComplete="new-password"
value={keyDraft}
onChange={(event) => {
setKeyDraft(event.target.value)
setTestedEndpoint('')
}}
placeholder={connection?.key_configured ? '留空 = 保留原密钥' : '粘贴 API Key'}
aria-label={`${title} API Key`}
/>
</label>
<p className="hint">
「测试连接」会真实请求该实例的知识库列表,并区分地址不可达 / 密钥无效 / 无权限 /
成功;换了地址或密钥必须先测通才能保存。撤销绑定请把下方目标库留空。
</p>
<div className="kb-binding-actions">
<button onClick={() => void test()} disabled={!canTest}>
{testing ? '正在测试…' : '测试连接'}
</button>
<button onClick={() => void save(saveAction)} disabled={!canSave}>
{saving ? '正在保存…' : '保存连接'}
</button>
{connection?.key_configured ? (
<button className="danger" onClick={clearKey} disabled={saving || testing}>
清除密钥
</button>
) : null}
</div>
{error ? (
<p className="error-message" role="alert">
{error}
</p>
) : null}
{message ? (
<p className="success-message" role="status">
{message}
</p>
) : null}
</div>
) : (
<p className="hint">仅管理员可修改连接与密钥;当前密钥只显示尾 4 位,任何接口都不会回读明文。</p>
)}
</div>
)
}
+4
View File
@@ -11,6 +11,8 @@ export interface ProductionBindings {
production_base_url: string
production_connected: boolean
production_message: string
frozen: number
retargetable: number
}
const record = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
@@ -25,6 +27,8 @@ function projection(item: Record<string, unknown>): ProductionBindings {
production_base_url: typeof item.production_base_url === 'string' ? item.production_base_url : '',
production_connected: item.production_connected === true,
production_message: typeof item.production_message === 'string' ? item.production_message : '',
frozen: typeof item.frozen === 'number' ? item.frozen : 0,
retargetable: typeof item.retargetable === 'number' ? item.retargetable : 0,
}
}
+4
View File
@@ -5,6 +5,8 @@ export interface RoutingBindings {
external_kb_id: string
internal_env_fallback: boolean
external_env_fallback: boolean
internal_fallback_kb_id: string
external_fallback_kb_id: string
internal_bound_by_ui: boolean
external_bound_by_ui: boolean
internal_kb_name: string
@@ -30,6 +32,8 @@ function bindingProjection(item: Record<string, unknown>): RoutingBindings {
external_kb_id: typeof item.external_kb_id === 'string' ? item.external_kb_id : '',
internal_env_fallback: item.internal_env_fallback === true,
external_env_fallback: item.external_env_fallback === true,
internal_fallback_kb_id: typeof item.internal_fallback_kb_id === 'string' ? item.internal_fallback_kb_id : '',
external_fallback_kb_id: typeof item.external_fallback_kb_id === 'string' ? item.external_fallback_kb_id : '',
internal_bound_by_ui: item.internal_bound_by_ui === true,
external_bound_by_ui: item.external_bound_by_ui === true,
internal_kb_name: typeof item.internal_kb_name === 'string' ? item.internal_kb_name : '',
+26
View File
@@ -882,3 +882,29 @@ button.link {
font-size: 0.8rem;
line-height: 1.5;
}
/* 连接卡:地址 + 写-only 密钥 + 真实列库测试。它嵌在既有的「测试/生产知识库绑定」
分区里,所以只做一个轻量内框,不另起一套分区样式。 */
.weknora-connection-card {
display: grid;
gap: 8px;
margin: 10px 0 16px;
padding: 12px;
border: 1px solid var(--border-base);
border-radius: 10px;
background: var(--bg-soft);
}
.weknora-connection-card .kb-binding-grid {
margin: 0;
grid-template-columns: 1fr;
}
.kb-binding-actions {
display: flex;
gap: 8px;
flex-wrap: wrap;
}
.kb-binding-actions button.danger {
border-color: var(--c-fail);
background: #fff;
color: var(--c-fail);
}
+116
View File
@@ -0,0 +1,116 @@
import { describe, expect, it, vi } from 'vitest'
import {
fetchWeKnoraConnections,
keyLabel,
saveWeKnoraConnection,
testWeKnoraConnection,
verificationLabel,
} from './weknoraConnections'
import type { WeKnoraConnection, WeKnoraVerification } from './weknoraConnections'
const connection: WeKnoraConnection = {
environment: 'production',
endpoint: 'http://172.29.151.11:18093',
key_configured: true,
key_tail: '9f2c',
verification: 'ok',
library_count: 4,
checked_at: '2026-11-22T07:00:00Z',
updated_by: 'admin',
revision: 3,
storage_ready: true,
}
describe('WeKnora connection API', () => {
it('projects only the safe fields and never surfaces a key', async () => {
vi.stubGlobal(
'fetch',
vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
data: [{ ...connection, api_key: 'placeholder-key-value', key_ciphertext: 'AAAA' }],
}),
{ status: 200 }
)
)
)
const [projected] = await fetchWeKnoraConnections()
expect(projected.key_tail).toBe('9f2c')
expect(projected).not.toHaveProperty('api_key')
expect(projected).not.toHaveProperty('key_ciphertext')
vi.unstubAllGlobals()
})
it('renders the four answers distinctly', () => {
const withVerification = (verification: WeKnoraVerification): WeKnoraConnection => ({ ...connection, verification })
expect(verificationLabel({ ...connection, library_count: 4 })).toBe('可达 · 已读到 4 个知识库')
expect(verificationLabel(withVerification('key_invalid'))).toBe('密钥无效')
expect(verificationLabel(withVerification('key_forbidden'))).toBe('密钥无权限读取知识库列表')
expect(verificationLabel(withVerification('unreachable'))).toBe('地址不可达')
expect(verificationLabel(null)).toBe('未配置')
expect(keyLabel(connection)).toBe('已配置 · 尾9f2c')
expect(keyLabel({ ...connection, key_configured: false, key_tail: '' })).toBe('未配置')
})
it('tests through the environment route and keeps the outcome', async () => {
const fetchMock = vi.fn().mockResolvedValue(
new Response(
JSON.stringify({
data: {
environment: 'production',
endpoint: connection.endpoint,
outcome: 'key_forbidden',
library_count: 0,
message: '密钥无权限读取知识库列表(403)',
checked_at: '2026-11-22T07:00:00Z',
},
}),
{ status: 200 }
)
)
vi.stubGlobal('fetch', fetchMock)
const result = await testWeKnoraConnection('production', {
endpoint: connection.endpoint,
api_key: 'sk-live-x',
key_action: 'replace',
})
expect(result.outcome).toBe('key_forbidden')
expect(result.message).toContain('无权限')
expect(fetchMock.mock.calls[0][0]).toBe('/api/v1/weknora-connections/production/test')
expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toMatchObject({ key_action: 'replace' })
vi.unstubAllGlobals()
})
it('saves with the revision and an idempotency key', async () => {
const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ data: connection }), { status: 200 }))
vi.stubGlobal('fetch', fetchMock)
const saved = await saveWeKnoraConnection('production', {
endpoint: connection.endpoint,
key_action: 'keep',
base_revision: 2,
})
expect(saved.revision).toBe(3)
const [url, init] = fetchMock.mock.calls[0]
expect(url).toBe('/api/v1/weknora-connections/production')
expect(init.method).toBe('PUT')
expect(init.headers['Idempotency-Key']).toBeTruthy()
expect(JSON.parse(init.body)).toMatchObject({ key_action: 'keep', base_revision: 2 })
vi.unstubAllGlobals()
})
it('surfaces the server reason when a save is refused', async () => {
vi.stubGlobal(
'fetch',
vi
.fn()
.mockResolvedValue(
new Response(JSON.stringify({ error: '请先点「测试连接」并成功,才能保存这一侧的配置' }), { status: 400 })
)
)
await expect(
saveWeKnoraConnection('test', { endpoint: 'http://127.0.0.1:8092', key_action: 'keep', base_revision: 0 })
).rejects.toThrow('测试连接')
vi.unstubAllGlobals()
})
})
+145
View File
@@ -0,0 +1,145 @@
import { newOperationID } from './operationKey'
// 连接状态:地址 + 「有没有配过密钥」+ 上一次真实列库的结论。密钥本身永远不回到
// 页面,只回显尾 4 位。
export type WeKnoraVerification = 'not_configured' | 'ok' | 'unreachable' | 'key_invalid' | 'key_forbidden'
export type WeKnoraTestOutcome = 'ok' | 'unreachable' | 'key_invalid' | 'key_forbidden'
export type WeKnoraEnvironment = 'test' | 'production'
export interface WeKnoraConnection {
environment: WeKnoraEnvironment
endpoint: string
key_configured: boolean
key_tail: string
verification: WeKnoraVerification
library_count: number
checked_at: string | null
updated_by: string
revision: number
storage_ready: boolean
}
export interface WeKnoraConnectionTestResult {
environment: WeKnoraEnvironment
endpoint: string
outcome: WeKnoraTestOutcome
library_count: number
message: string
checked_at: string
}
type KeyAction = 'keep' | 'replace' | 'clear'
const record = (value: unknown): value is Record<string, unknown> =>
Boolean(value) && typeof value === 'object' && !Array.isArray(value)
const verificationOf = (value: unknown): WeKnoraVerification =>
value === 'ok' ||
value === 'unreachable' ||
value === 'key_invalid' ||
value === 'key_forbidden' ||
value === 'not_configured'
? value
: 'not_configured'
function projection(item: Record<string, unknown>): WeKnoraConnection {
const environment = item.environment === 'production' ? 'production' : 'test'
return {
environment,
endpoint: typeof item.endpoint === 'string' ? item.endpoint : '',
key_configured: item.key_configured === true,
key_tail: typeof item.key_tail === 'string' ? item.key_tail : '',
verification: verificationOf(item.verification),
library_count: typeof item.library_count === 'number' ? item.library_count : 0,
checked_at: typeof item.checked_at === 'string' ? item.checked_at : null,
updated_by: typeof item.updated_by === 'string' ? item.updated_by : '',
revision: typeof item.revision === 'number' ? item.revision : 0,
storage_ready: item.storage_ready === true,
}
}
async function reason(response: Response, fallback: string): Promise<string> {
try {
const body = (await response.json()) as unknown
if (record(body) && typeof body.error === 'string' && body.error) return body.error
} catch {
/* keep the status text */
}
return `${fallback}(HTTP ${response.status})`
}
export async function fetchWeKnoraConnections(signal?: AbortSignal): Promise<WeKnoraConnection[]> {
const response = await fetch('/api/v1/weknora-connections', { signal, headers: { Accept: 'application/json' } })
if (!response.ok) throw new Error(await reason(response, '读取 WeKnora 连接失败'))
const value = (await response.json()) as unknown
if (!record(value) || !Array.isArray(value.data)) throw new Error('WeKnora 连接响应无效')
return value.data.filter(record).map(projection)
}
export async function testWeKnoraConnection(
environment: WeKnoraEnvironment,
input: { endpoint: string; api_key?: string; key_action?: KeyAction },
signal?: AbortSignal
): Promise<WeKnoraConnectionTestResult> {
const response = await fetch(`/api/v1/weknora-connections/${environment}/test`, {
method: 'POST',
signal,
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify(input),
})
if (!response.ok) throw new Error(await reason(response, '测试连接失败'))
const value = (await response.json()) as unknown
if (!record(value) || !record(value.data)) throw new Error('测试连接响应无效')
const data = value.data
return {
environment: data.environment === 'production' ? 'production' : 'test',
endpoint: typeof data.endpoint === 'string' ? data.endpoint : input.endpoint,
outcome:
data.outcome === 'key_invalid' || data.outcome === 'key_forbidden' || data.outcome === 'unreachable'
? data.outcome
: 'ok',
library_count: typeof data.library_count === 'number' ? data.library_count : 0,
message: typeof data.message === 'string' ? data.message : '',
checked_at: typeof data.checked_at === 'string' ? data.checked_at : '',
}
}
export async function saveWeKnoraConnection(
environment: WeKnoraEnvironment,
input: { endpoint: string; api_key?: string; key_action: KeyAction; base_revision: number },
signal?: AbortSignal
): Promise<WeKnoraConnection> {
const response = await fetch(`/api/v1/weknora-connections/${environment}`, {
method: 'PUT',
signal,
headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'Idempotency-Key': newOperationID() },
body: JSON.stringify(input),
})
if (!response.ok) throw new Error(await reason(response, '保存连接失败'))
const value = (await response.json()) as unknown
if (!record(value) || !record(value.data)) throw new Error('保存连接响应无效')
return projection(value.data)
}
// verificationLabel 是页面唯一的口径:四态说清「哪里不通」,成功时带库数量。
export function verificationLabel(connection: WeKnoraConnection | null): string {
if (!connection || !connection.endpoint) return '未配置'
switch (connection.verification) {
case 'ok':
return `可达 · 已读到 ${connection.library_count} 个知识库`
case 'key_invalid':
return '密钥无效'
case 'key_forbidden':
return '密钥无权限读取知识库列表'
case 'unreachable':
return '地址不可达'
default:
// 填了地址但还没测过:说「尚未验证」,不要谎报不可达。
return '尚未验证'
}
}
export function keyLabel(connection: WeKnoraConnection | null): string {
if (!connection || !connection.key_configured) return '未配置'
return `已配置 · 尾${connection.key_tail || '—'}`
}