feat(asset): 清理被截断的结尾图片引用,修复整单 502

仓库首次入库(此前仅存在于本地工作区与测试服构建产物中,未上传)。

改动(src/knowledge_adapter/asset_content_processor.py):
- 新增 _TRUNCATED_TRAILING_MARKDOWN_RESOURCE_IMAGE 规则,清除 chunk 末尾被截断的
  ![](resource://xxxx 残片(WeKnora 分块在图片引用中间截断时产生,旧逻辑无法匹配完整引用,
  残留 resource:// 触发 ContentProcessingError,导致整单 502)
- 回归测试 tests/test_asset_content_processor.py::
  test_truncated_trailing_markdown_resource_image_is_removed

验证证据:
- 测试服 120.76.217.51,镜像 knowledge-adapter-service:reviewed-test-aeab4b5fca2d
  (release aeab4b5fca2d8661):KB d015d05c-25c8-4d63-b2ab-e8590d3c2dfb 5 个查询全部
  http=200、records=5、残留 resource:// = 0;KB b9dacd62 无退化;容器日志无 error/exception
- 本地:pytest 141 项全通过、ruff 全通过
- 该文件与 258c31e0fe07fd08 源码的差异经逐文件 md5 比对,为唯一变更文件
This commit is contained in:
姚章浩
2026-09-16 10:01:27 +08:00
commit 693cd952cd
64 changed files with 7869 additions and 0 deletions
+97
View File
@@ -0,0 +1,97 @@
# Knowledge Adapter Architecture
## Scope
Knowledge Adapter is a small protocol and security boundary between Dify and an existing WeKnora deployment. It does not modify WeKnora and does not reimplement RAG, embedding, reranking, parsing, or object storage.
Public API:
- `POST /retrieval`: authenticated Dify External Knowledge retrieval.
- `GET /i/{UUID}`: anonymous stable image URL; possession of the UUID URL grants image access.
- `GET /healthz`: process liveness only; no dependency or configuration disclosure.
## Runtime topology
```text
Dify
-> HTTPS POST /retrieval
-> host Nginx
-> Adapter :8080
-> private WeKnora POST /api/v1/knowledge-search
-> projection + image rewrite + final-content budgets
-> Dify records
Browser
-> HTTPS GET /i/{UUID}
-> host Nginx
-> Adapter
-> Adapter DB asset_mapping (active row only)
-> read-only mounted static AK Secret files
-> Private OSS V4 Presigned GET URL (600 seconds)
-> HTTP 302
```
Nginx is the TLS boundary. Compose publishes Adapter only at `127.0.0.1:18080`; the Adapter joins a configurable external `WEKNORA_NETWORK_NAME` so `WEKNORA_BASE_URL=http://app:8080` reaches the existing WeKnora App without changing WeKnora source or Compose. Its separate `adapter` bridge remains the default network for isolation. No database, Redis, metadata, or OSS endpoint is exposed by this project.
## Components
### Retrieval path
1. `DifyKeyAuthenticator` compares the presented key hash against `DIFY_KEY_HASH_CURRENT` and optional `DIFY_KEY_HASH_NEXT` in constant time.
2. `RetrievalService` checks the knowledge-base allowlist and clamps TopK.
3. `WeKnoraClient` calls the existing private WeKnora search endpoint with a fixed base URL and timeout.
4. Each returned chunk is revalidated against the requested knowledge-base UUID.
5. `AssetContentProcessor` rewrites permitted image locators and rejects unprocessed internal locators.
6. Per-chunk and total limits are applied to the final rewritten content.
### Image mapping path
```text
resource://handle
-> Adapter DB lookup
-> on miss only: dedicated WeKnora read-only DB resolver
-> fixed tenant/backend/provider/bucket checks
-> Adapter DB atomic mapping insert
-> https://assets.example.com/i/{UUID}
```
`asset_mapping` stores only the stable UUID mapping, source reference, OSS object key, content type, creation time, and active/disabled status. It never stores credentials or a Presigned URL.
### Image redirect path
`GET /i/{UUID}` accepts only a UUID path value. The caller cannot provide bucket, region, object key, endpoint, expiry, or another URL. The service reads an active mapping, reads the dedicated OSS AccessKey pair from static AK Secret files, produces a V4 GET URL for the configured Private OSS bucket, and returns it only in the 302 `Location` header. `Cache-Control: no-store` forces a later visit to generate a fresh 600-second URL while the public UUID remains unchanged.
## Data and identity boundaries
- Adapter DB account: read/write only for Adapter-owned `asset_mapping`.
- WeKnora read-only DB account: field-level `SELECT` only on the required resource locator columns.
- WeKnora API key: search API only; mounted as a Secret file.
- OSS RAM user static AK: separate test/production identities; production policy is `oss:GetObject` only for the reviewed bucket/object prefix.
- Dify key: Adapter stores only SHA-256 hashes; raw keys remain outside Git and Compose environment.
The two database accounts must never be reused across databases.
## Availability and scaling
The service is stateless except for Adapter DB mappings. Multiple Adapter replicas can share the same Adapter DB; mapping creation is conflict-safe. Each process currently opens up to five Adapter DB connections and two WeKnora read-only DB connections. Capacity planning must multiply these limits by process and replica count before scaling.
`/healthz` proves only that the Adapter process can answer. Dependency readiness and business E2E are separate acceptance gates.
## Failure contract
- Invalid request or disallowed KB: fixed 400.
- WeKnora unavailable: fixed 503.
- Invalid WeKnora response or unsafe content: fixed 502.
- Missing/disabled image UUID: empty 404; signer is not called.
- Adapter DB, OSS credential files, or signing unavailable: empty 503.
- Unexpected error: fixed JSON 500.
Every response carries a sanitized `X-Request-ID`. Request logs use route templates and fixed error codes, not raw URLs or sensitive content.
## Non-goals
- Production deployment before Slice 9 review acceptance.
- WeKnora source or schema changes.
- Public OSS bucket access.
- Arbitrary URL fetch/upload, proxying, or SSRF-capable media import.
- OAuth, JWT, multi-tenancy, an administration UI, LLM summarization, or replacement retrieval logic.
+129
View File
@@ -0,0 +1,129 @@
# Slice 9 Verification and E2E Audit Report
- Project: Knowledge Adapter Service
- Repository: `/home/zheromiku/knowledge-adapter-service`
- Audit timestamp: `2026-08-24T18:44:35+08:00`
- Environment observed: local physical Inspur NF5568M4 host
- Scope: code/config validation and authorized read-only test-environment probes
- Production deployment: prohibited and not attempted
## Executive conclusion
The application implementation and source-delivery gates pass. The initial pre-report full suite completed with `133 passed in 1.06s`; after adding the audit artifact contract, the final full suite completed with `134 passed in 1.15s`. Ruff returned `All checks passed!`; the RAM policy parsed; the documentation citation ledger verified; and Docker Compose rendered successfully.
The real `Dify → Adapter → WeKnora → Adapter DB → OSS` E2E is **BLOCKED**, not failed and not passed. This host lacks the three dedicated Adapter Secret files, an authorized Docker daemon, a running Adapter candidate, a test Dify binding, and—critically—the Alibaba Cloud ECS RAM Role/IMDSv2 environment required by the production signer. No cloud result has been fabricated.
Production deployment remains **NOT RUN** by design.
## Requirement-to-evidence matrix
| Gate | Status | Evidence |
|---|---|---|
| Python runtime | PASS | `uv run python --version` → Python 3.12.11 |
| Full pytest before audit artifact | PASS | 133 tests collected; `133 passed in 1.06s` |
| Final full pytest | PASS | 134 tests collected; `134 passed in 1.15s` |
| Ruff | PASS | `uv run ruff check src tests` → `All checks passed!` |
| RAM policy JSON | PASS | `python -m json.tool ...` exited 0 |
| OSS permission contract | PASS (static) | Exact Action is `oss:GetObject`; resource is one configured bucket/tenant prefix |
| Security source citations | PASS | grounded-citations strict verify exited 0; four registered sources |
| Compose parse/render | PASS | `docker compose ... config --quiet` exited 0 |
| Compose service inventory | PASS | exactly `adapter`; image `knowledge-adapter-service:reviewed-test` |
| Existing WeKnora network integration | PASS (static) | Adapter joins configurable external `WEKNORA_NETWORK_NAME`; local baseline is `weknora071full-network`, App URL `http://app:8080` |
| Existing WeKnora /health | PASS (runtime/read-only) | `http://127.0.0.1:8080/health` returned HTTP 200 JSON |
| Dockerfile native build check | BLOCKED | Docker daemon permission denied at `/var/run/docker.sock`; no sudo or socket workaround used |
| Docker image build | BLOCKED | Same Docker daemon permission boundary |
| Container runtime/UID/mount health | BLOCKED | Adapter was not built or started; `127.0.0.1:18080` is closed |
| Nginx native syntax test | BLOCKED | `nginx binary unavailable` on this host; source-contract test passes only |
| Adapter DB migration rehearsal | BLOCKED | dedicated `asset_database_url` Secret/account/database are absent |
| WeKnora field-level grant rehearsal | BLOCKED | dedicated `weknora_readonly_database_url` Secret/account is absent |
| Test Dify external knowledge call | BLOCKED | no test Dify endpoint/binding/key was provided to this environment |
| Real cloud E2E | BLOCKED | no running Adapter candidate and no Alibaba ECS RAM Role/IMDSv2 context |
| Private OSS anonymous denial | BLOCKED | no authorized test-ECS signer path and no approved object fixture |
| OSS V4 signed-object fetch | BLOCKED | same prerequisite gap; Presigned URL was not generated or printed |
| 600-second expiry | BLOCKED | requires waiting against a real signed URL on test ECS |
| stable UUID re-signing | BLOCKED | requires active Adapter DB mapping and two real redirect requests |
| historical Dify image reopen | BLOCKED | requires a real Dify conversation and stable UUID fixture |
| Production deployment | NOT RUN | explicitly outside the approved scope |
## Commands actually run
```text
uv run pytest -o addopts='' tests
uv run ruff check src tests
python -m json.tool deploy/ram/knowledge-adapter-oss-read-policy.json
docker compose --env-file deploy/adapter.env.example \
-f deploy/docker-compose.adapter.yml config --quiet
docker compose --env-file deploy/adapter.env.example \
-f deploy/docker-compose.adapter.yml config --services
docker compose --env-file deploy/adapter.env.example \
-f deploy/docker-compose.adapter.yml config --images
docker buildx build --check --progress=plain .
python .../grounded-citations/scripts/sources.py verify docs/security.md --strict
```
The build-check command returned only the Docker daemon permission error. It did not build an image or change container state.
## Read-only prerequisite findings
### Listening endpoints
```text
127.0.0.1:8080 open existing WeKnora App
127.0.0.1:8088 open existing WeKnora UI
127.0.0.1:18080 closed Adapter candidate not running
127.0.0.1:80 closed
127.0.0.1:443 closed
```
### Dedicated Secret files
All required files are missing:
```text
/opt/knowledge-adapter/secrets/weknora_api_key
/opt/knowledge-adapter/secrets/asset_database_url
/opt/knowledge-adapter/secrets/weknora_readonly_database_url
```
No Secret content was read or printed.
### ECS role prerequisite
The observed host reports `sys_vendor=Inspur` and `product_name=NF5568M4`. It is not the target Alibaba ECS test instance. The signer intentionally supports only ECS RAM Role temporary credentials via IMDSv2 and has no long-lived AccessKey fallback, so a real OSS redirect cannot be accepted on this host.
## Security assertions retained
- No WeKnora source or schema was modified.
- No production system was contacted or deployed.
- No Docker permission bypass or sudo was used.
- No raw Dify/WeKnora key, database DSN, OSS AccessKey, STS token, object key, Authorization header, knowledge body, or Presigned URL was printed or committed.
- No migration or grant was applied.
- No OSS bucket ACL/policy was changed.
- No object was uploaded, copied, deleted, or made public.
- No caller-controlled bucket, object key, endpoint, expiry, or arbitrary URL path was introduced.
## Remaining test-ECS acceptance procedure
The following steps must execute on an authorized Alibaba ECS **test** instance after the prerequisites are provisioned:
1. Confirm the reviewed ECS RAM Role is attached and IMDSv2 temporary credentials resolve without long-lived AK/SK.
2. Confirm the OSS bucket remains Private and the role policy grants only the reviewed `oss:GetObject` prefix.
3. Create the dedicated Adapter DB and WeKnora field-level read-only accounts; place all three values in UID 10001, mode `0400` Secret files.
4. Run the up migration and field-level grant in disposable/test databases, then prove unrelated columns/tables and all writes are denied to the WeKnora role.
5. Build the reviewed image, run native `nginx -t` against the complete target configuration, and start only the Adapter candidate.
6. Verify runtime UID 10001, read-only root, Secret mounts, external WeKnora network, `/healthz`, and sanitized logs.
7. Configure a test Dify External Knowledge endpoint and execute one allowlisted query containing an approved image fixture.
8. Prove Dify receives only the stable UUID URL and no locator/object key/internal endpoint/signature.
9. Request the stable UUID, follow the 302 without displaying its Location, and verify the expected object content/hash.
10. Prove direct anonymous OSS access is denied.
11. Wait beyond the fixed 600-second expiry and prove the old temporary URL is denied.
12. Request the unchanged stable UUID again and prove stable UUID re-signing yields a working fresh temporary URL.
13. Reopen a historical Dify message containing the UUID link and verify the image still loads.
14. Export sanitized request-ID-correlated evidence and rerun the full suite/Ruff/config gates before review.
## Decision
- Code and static delivery package: **PASS**.
- Existing WeKnora liveness: **PASS**.
- Real cloud E2E: **BLOCKED** pending test-ECS prerequisites.
- Production readiness/deployment: **NOT APPROVED / NOT RUN**.
+144
View File
@@ -0,0 +1,144 @@
# Test Deployment and Rollback
> **TEST ENVIRONMENT ONLY**
>
> Production deployment is prohibited until Slice 9 real E2E evidence and the audit report are reviewed and explicitly accepted. This document is a prepared operator runbook, not authorization to execute it.
## Delivered files
```text
Dockerfile
deploy/docker-compose.adapter.yml
deploy/adapter.env.example
deploy/nginx/knowledge-adapter.conf
deploy/ram/knowledge-adapter-oss-read-policy.json
deploy/sql/weknora_readonly_grants.sql
migrations/0001_asset_mapping.up.sql
migrations/0001_asset_mapping.down.sql
```
## Prerequisites
- Dedicated test OSS AccessKey pair; test and production identities must be different.
- Private OSS bucket in the configured region.
- Existing private WeKnora API endpoint.
- Dedicated Adapter PostgreSQL database/login.
- Different dedicated WeKnora read-only PostgreSQL login.
- Host Nginx and a test TLS certificate for the reviewed public hostname.
- Docker Compose operated by an authorized human; this repository does not modify Docker daemon permissions.
## 1. Prepare non-secret configuration
Copy `deploy/adapter.env.example` outside Git, for example to `/opt/knowledge-adapter/adapter.env`, and replace every placeholder. Do not add raw API keys or database URLs.
`DIFY_KEY_HASH_CURRENT` is the SHA-256 digest of the active Dify key. `DIFY_KEY_HASH_NEXT` remains empty until a dual-slot rotation.
Review these invariants:
- `ASSET_PUBLIC_BASE_URL` exactly matches the HTTPS Nginx hostname.
- `WEKNORA_NETWORK_NAME` names an existing external Docker network and `WEKNORA_BASE_URL` resolves the existing WeKnora App service on it; the test baseline uses `weknora071full-network` and `http://app:8080`.
- `OSS_CREDENTIAL_MODE=static_ak`; `OSS_REGION` and `OSS_BUCKET` match the test resources.
- `OSS_ACCESS_KEY_ID_HOST_FILE` and `OSS_ACCESS_KEY_SECRET_HOST_FILE` point to the two protected host Secret files.
- the KB allowlist contains only approved UUIDs;
- all response budgets match the approved values.
## 2. Prepare Secret files
Create an untracked `/opt/knowledge-adapter/secrets` directory. Populate each file through an approved secret manager or interactive editor; never put a secret in a command argument or shell history.
Required files:
```text
weknora_api_key
asset_database_url
weknora_readonly_database_url
oss_access_key_id
oss_access_key_secret
```
Set directory mode `0700`. Set each file owner to UID/GID `10001:10001` and mode `0400`. Confirm each file is non-empty without printing its contents. The two database DSNs must identify different accounts and databases. Never place either OSS value in `adapter.env`.
## 3. Provision database permissions
A DBA reviews and applies `migrations/0001_asset_mapping.up.sql` only to the dedicated Adapter database. Separately, a WeKnora DBA reviews and applies `deploy/sql/weknora_readonly_grants.sql` to the dedicated read-only role.
The application does not run migration automatically. Before migration:
1. take a database-native backup;
2. verify the backup catalog is readable;
3. record the current schema state;
4. apply the migration in the test database;
5. verify table/index constraints and role privileges.
The down migration drops Adapter mapping state and is destructive. Do not use it as routine rollback after data exists.
## 4. Review the OSS static AK identity
For the approved test window, the existing test-only AK may be used from the two Secret files. Before production, create a separate RAM user and AccessKey, replace `${OSS_BUCKET}` and `${WEKNORA_TENANT_ID}` in `deploy/ram/knowledge-adapter-oss-read-policy.json`, and confirm the only Action is `oss:GetObject` and the only Resource is the intended production object prefix. Do not reuse the test AK or place AccessKey values in environment variables.
## 5. Render configuration
The required read-only render gate is `docker compose config`; it must pass before any build or runtime action.
From the repository root, an authorized operator can perform a read-only render:
```text
docker compose --env-file /opt/knowledge-adapter/adapter.env \
-f deploy/docker-compose.adapter.yml config --quiet
```
Then inspect the rendered service for image/build source, loopback port, UID 10001, Secret mount targets, resource limits, and healthcheck. Rendering must not print Secret file contents.
## 6. Build and start the test candidate
Build only after source tests, Ruff, JSON validation, and Compose rendering pass. Use an immutable reviewed image tag rather than `latest`. Starting/recreating the candidate requires a separate operator approval because it changes runtime state.
The prepared Compose file contains only the Adapter; it does not create or replace PostgreSQL, Redis, WeKnora, Nginx, or OSS resources.
## 7. Install Nginx test configuration
Review `deploy/nginx/knowledge-adapter.conf` and replace the example hostname and certificate paths. Validate the complete host Nginx configuration before reload. The Adapter upstream remains `127.0.0.1:18080`.
Nginx rules intentionally:
- reject cleartext HTTP;
- expose only `/retrieval`, `/i/{UUID}`, and local `/healthz`;
- limit methods, body size, and request rate;
- sanitize `X-Request-ID`;
- disable access logs;
- pass 302 `Location` without logging it.
Installing or reloading host Nginx is outside this repository and requires explicit operator approval.
## 8. Test-environment acceptance
Do not print credentials or the 302 Location value. Record only sanitized results:
1. container health becomes healthy and `GET /healthz` returns 200;
2. no-auth and wrong-key `/retrieval` return 401;
3. allowlisted retrieval returns valid Dify records;
4. non-allowlisted KB returns fixed 400;
5. rewritten content has no internal locator, private endpoint, local path, object key, or signature;
6. valid `/i/{UUID}` returns 302 with `no-store` and a V4 URL whose expiry class is 600 seconds;
7. direct anonymous OSS object GET is denied;
8. following the 302 retrieves the expected test object;
9. a later visit to the same stable UUID produces a fresh temporary URL;
10. missing/disabled/malformed image IDs do not invoke OSS signing;
11. structured logs correlate request IDs without prohibited values;
12. CPU/RAM, database pool usage, upstream latency, and error rates are recorded.
The full real E2E belongs to Slice 9.
## Rollback
Application rollback is image/config rollback, not database destruction:
1. stop routing new test traffic at Nginx;
2. preserve sanitized logs and current rendered configuration;
3. restore the previously reviewed image tag and non-secret env file;
4. restore prior Secret files only when credential rotation caused the failure;
5. recreate only the Adapter service;
6. verify `/healthz`, authentication, retrieval, and stable image redirects;
7. restore Nginx routing.
Do not run `down -v`, prune volumes, drop `asset_mapping`, revoke the active AK before rollback is proven, or restore over a database without a separately reviewed recovery plan and verified backup.
+356
View File
@@ -0,0 +1,356 @@
# 测试环境 WeKnora 检索 API 调用说明
## 1. 当前状态
公网HTTPS链路已经通过真实验收:
```text
Dify/业务后端
→ https://weknora-api-test.dobot.cn/retrieval
→ 公网测试入口
→ 测试ECS Nginx:80
→ Knowledge Adapter:18080
→ WeKnora knowledge-search
```
真实验收结果:
```text
检索:HTTP 200
records:5
稳定图片UUID:15
图片:稳定UUID 302 → 私有OSS签名取图 HTTP 200
```
完整且已脱敏的真实请求与响应:
```text
docs/test-api-request-response.txt
```
## 2. 接口地址与安全边界
### 检索地址
```http
POST https://weknora-api-test.dobot.cn/retrieval
```
这是服务端到服务端接口:
```text
Dify可以直接调用
业务后端/BFF可以直接调用
浏览器前端不能携带Adapter API Key直接调用
```
浏览器推荐链路:
```text
浏览器前端
→ 业务后端/BFF
→ Adapter
→ WeKnora
```
禁止把真实API Key写入:
- 前端JavaScript或打包产物;
- Git仓库;
- URL查询参数;
- LocalStorage或SessionStorage;
- 普通日志、埋点或错误上报。
## 3. 请求方法
### Headers
```http
Authorization: Bearer [TEST_DIFY_KEY]
Content-Type: application/json
Accept: application/json
X-Request-ID: <可选,建议使用UUID>
```
对外调用使用的是Dify Bearer Key。WeKnora API Key和OSS凭据只由Adapter内部使用,不能提供给Dify或浏览器。
### Body
```json
{
"knowledge_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"query": "接线",
"retrieval_setting": {
"top_k": 5,
"score_threshold": 0.2
}
}
```
### 字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---:|---:|---|
| `knowledge_id` | UUID字符串 | 是 | 测试环境“对外知识库”固定为 `b9dacd62-87eb-4b38-a6b6-85f68e144796` |
| `query` | 字符串 | 是 | 用户问题;去除首尾空格后不能为空,最多2000字符 |
| `retrieval_setting.top_k` | 整数 | 是 | 至少为1,当前上限为5 |
| `retrieval_setting.score_threshold` | 浮点数 | 是 | 范围0至1;业务建议初始使用0.2,排查召回问题时可临时使用0 |
| `metadata_condition` | 对象 | 否 | 当前不支持非空过滤条件,调用方应省略 |
`knowledge_id`应由Dify或业务后端固定,不能接受浏览器任意指定。
## 4. 应答格式
成功响应:
```json
{
"records": [
{
"content": "Markdown格式的知识片段",
"score": 0.82,
"title": "文档标题",
"metadata": {
"knowledge_base_id": "知识库UUID",
"knowledge_id": "文档UUID",
"chunk_id": "Chunk UUID",
"chunk_index": 1,
"chunk_type": "text"
}
}
]
}
```
真实公网响应节选(`content`为缩写,完整正文见TXT样本):
```json
{
"records": [
{
"content": "<Markdown知识片段,包含稳定的 /i/<UUID> 图片地址>",
"score": 0.5314404987902756,
"title": "Dobot Magician Go用户手册V1.1_20240624_cn.pdf",
"metadata": {
"knowledge_base_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"knowledge_id": "3c878f4e-bfea-4c5c-b122-b63ba9db4e34",
"chunk_id": "d674ba02-7769-4e9a-8596-961cb50e1f75",
"chunk_index": 53,
"chunk_type": "text"
}
}
]
}
```
字段说明:
| 字段 | 类型 | 说明 |
|---|---:|---|
| `records` | 数组 | 检索结果;没有命中时为空数组 |
| `records[].content` | 字符串 | Markdown知识片段,不是大模型生成的最终答案 |
| `records[].score` | 浮点数 | 当前检索相关度分数;不要跨模型或跨版本硬编码绝对含义 |
| `records[].title` | 字符串 | 来源文档标题 |
| `records[].metadata` | 对象 | 知识库、文档和Chunk审计标识 |
该接口只负责检索。Dify拿到`records`后,再将知识片段交给大模型生成最终回答。
## 5. curl调用示例
真实Key应由运行环境或密钥系统注入,不要直接写进脚本:
```bash
curl --request POST \
'https://weknora-api-test.dobot.cn/retrieval' \
--header "Authorization: Bearer ${WEKNORA_ADAPTER_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "X-Request-ID: $(python3 -c 'import uuid; print(uuid.uuid4())')" \
--data '{
"knowledge_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"query": "接线",
"retrieval_setting": {
"top_k": 5,
"score_threshold": 0.2
}
}'
```
## 6. Node.js服务端调用示例
下面代码只能运行在Node.js服务端或BFF,不能放入浏览器包:
```js
import { randomUUID } from "node:crypto";
const ADAPTER_URL = "https://weknora-api-test.dobot.cn/retrieval";
const KNOWLEDGE_ID = "b9dacd62-87eb-4b38-a6b6-85f68e144796";
export async function retrieveKnowledge(query) {
const apiKey = process.env.WEKNORA_ADAPTER_API_KEY;
if (!apiKey) {
throw new Error("WEKNORA_ADAPTER_API_KEY is not configured");
}
const response = await fetch(ADAPTER_URL, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
Accept: "application/json",
"X-Request-ID": randomUUID(),
},
body: JSON.stringify({
knowledge_id: KNOWLEDGE_ID,
query,
retrieval_setting: {
top_k: 5,
score_threshold: 0.2,
},
}),
signal: AbortSignal.timeout(25000),
});
if (!response.ok) {
throw new Error(`Knowledge retrieval failed: HTTP ${response.status}`);
}
const body = await response.json();
if (!body || !Array.isArray(body.records)) {
throw new Error("Invalid knowledge retrieval response");
}
return body.records;
}
```
日志中只建议记录:
```text
X-Request-ID、HTTP状态、耗时、records数量
```
不要记录:
```text
Authorization、API Key、完整问题、完整知识正文、图片302 Location
```
## 7. 浏览器调用BFF示例
浏览器只调用业务后端,不携带Adapter API Key:
```js
const response = await fetch("/api/knowledge/retrieve", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ query: userInput }),
});
if (!response.ok) {
throw new Error(`检索失败:HTTP ${response.status}`);
}
const { records } = await response.json();
```
业务后端负责补充:
```text
Authorization
knowledge_id
retrieval_setting
X-Request-ID
```
## 8. Dify配置
在Dify外部知识库API中填写:
```text
Endpoint:
https://weknora-api-test.dobot.cn/retrieval
API Key:
测试环境Adapter原始Key
External Knowledge ID:
b9dacd62-87eb-4b38-a6b6-85f68e144796
```
不要把Dify直接指向WeKnora原生`/api/v1/knowledge-search`。协议转换、知识库白名单、响应裁剪和图片稳定URL都由Adapter负责。
## 9. 图片调用方法
检索结果中的图片使用稳定地址:
```text
https://weknora-api-test.dobot.cn/i/<UUID>
```
真实样例:
```text
https://weknora-api-test.dobot.cn/i/02e269e8-c4f0-4b3f-a41e-82f5b222a31f
```
前端直接将稳定地址作为图片地址:
```html
<img src="https://weknora-api-test.dobot.cn/i/<UUID>" alt="知识图片">
```
图片访问不需要Bearer Key:
```text
浏览器GET /i/<UUID>
→ Adapter查询有效映射
→ HTTP 302
→ 私有OSS 10分钟签名URL
→ 图片HTTP 200
```
注意:
- 保存和渲染稳定`/i/<UUID>`地址;
- 不保存、不打印、不缓存302后的OSS签名地址;
- 10分钟过期的是OSS签名地址,不是稳定UUID地址;
- 稳定UUID属于能力链接,不应进入无关日志或公开页面;
- OSS Bucket继续保持Private。
真实图片验收:
```text
稳定UUID:HTTP 302
Cache-Control:no-store
Referrer-Policy:no-referrer
私有OSS匿名访问:HTTP 403
短期签名取图:HTTP 200
类型:image/jpeg
大小:56,025 bytes
JPEG结构:有效
```
## 10. 错误码
| HTTP状态 | 含义 | 调用方处理 |
|---:|---|---|
| 200 | 成功 | 读取`records`,允许空数组 |
| 400 | 请求格式错误或知识库未授权 | 不重试;检查请求字段和固定`knowledge_id` |
| 401 | API Key缺失或错误 | 不重试;检查服务端Secret配置 |
| 403 | 请求方法被Nginx拒绝 | 不重试;确认使用`POST /retrieval`或`GET /i/<UUID>` |
| 404 | 路径或图片UUID不存在 | 不重试;检查地址 |
| 502 | WeKnora响应异常或内容处理失败 | 记录Request ID,有限重试并告警 |
| 503 | WeKnora超时、暂时不可用或图片签名失败 | 建议退避重试1至2次,仍失败则降级 |
不要自动重试400、401、403和404。
## 11. 联调检查表
- [x] 公网HTTPS回源测试ECS Nginx 80;
- [x] 保留`Host`、`Authorization`、`Content-Type`和`X-Request-ID`;
- [x] 无Key请求返回401;
- [x] 正确Key请求返回HTTP 200和`records`;
- [x] 有图结果返回稳定UUID,图片302和最终下载通过;
- [ ] 前端构建产物中确认不存在Adapter API Key;
- [ ] 业务日志中确认没有Authorization、完整正文和OSS签名URL;
- [ ] 生产环境使用独立域名、独立Key和独立知识库白名单。
+83
View File
@@ -0,0 +1,83 @@
# Key and Credential Rotation
All rotations are staged in the test environment first. Never print raw keys, DSNs, STS tokens, Presigned URLs, or Secret file contents. Every cutover needs a rollback copy outside Git and a post-change readback.
## Dify Bearer key
Dify rotation uses two SHA-256 hash slots so old and new callers can overlap briefly.
1. Generate the new raw key in an approved secret manager.
2. Calculate its SHA-256 digest without placing the raw key in shell history.
3. Set the digest as `DIFY_KEY_HASH_NEXT`; leave `DIFY_KEY_HASH_CURRENT` unchanged.
4. Recreate only the Adapter and verify both old and new keys.
5. Update Dify to the new raw key and verify real test retrieval.
6. Set the new digest as `DIFY_KEY_HASH_CURRENT` and clear `DIFY_KEY_HASH_NEXT`.
7. Recreate and verify that the new key works and old key fails.
8. Revoke/delete the old raw key from its secret store.
Rollback before step 6: restore the previous env file. Rollback after step 6: temporarily restore old current plus new next, recreate, and investigate. Raw keys never enter Compose environment; only `DIFY_KEY_HASH_CURRENT` and `DIFY_KEY_HASH_NEXT` do.
## WeKnora API Key
1. Create a new restricted WeKnora API Key without revoking the old key.
2. Write it to a sibling untracked Secret file using an approved secret manager/editor.
3. Set owner `10001:10001`, mode `0400`, and verify non-empty without printing.
4. Atomically replace `/opt/knowledge-adapter/secrets/weknora_api_key` on the same filesystem.
5. Recreate only the Adapter and run allowlisted retrieval.
6. Confirm request IDs reach WeKnora and logs contain no key.
7. Revoke the old WeKnora API Key.
Rollback: restore the previous Secret file atomically and recreate only the Adapter before revoking the old key.
## Adapter DB credential
The Adapter DB account may read/write only Adapter-owned mapping objects.
1. Create a new dedicated login/password and grant the same narrow privileges.
2. Test the new DSN from an isolated test client without displaying it.
3. Atomically replace `asset_database_url` with owner `10001:10001`, mode `0400`.
4. Recreate only the Adapter.
5. Verify mapping lookup, conflict-safe insert, and stable UUID redirect.
6. Disable the old login, observe, then remove it after the rollback window.
Rollback: re-enable the old login if needed, restore the previous Secret file, and recreate only the Adapter. Do not alter `asset_mapping` rows.
## WeKnora read-only DB credential
The WeKnora read-only DB account is separate from the Adapter DB account.
1. Create a new `NOINHERIT` login with no unrelated memberships.
2. Apply/review `deploy/sql/weknora_readonly_grants.sql` for the new role.
3. Prove permitted field-level SELECT succeeds and unrelated table/column/write access fails.
4. Atomically replace `weknora_readonly_database_url` with mode `0400`.
5. Recreate only the Adapter and verify first-time resource resolution.
6. disable the old login, observe, then remove it.
Rollback: restore the old role and Secret file; no WeKnora schema or data changes are part of rotation.
## OSS static AK
The Adapter reads the OSS AccessKey pair from two mode-`0400` Secret files. Test and production use different RAM users, keys, buckets, and Secret directories.
1. Create a second AccessKey for the same dedicated RAM user, or create a replacement dedicated RAM user with the same reviewed `oss:GetObject` policy.
2. Write the candidate ID and secret to sibling untracked files without printing either value.
3. Set owner `10001:10001`, mode `0400`, then atomically replace both active files within one maintenance window.
4. Recreate only the Adapter and verify 302 generation, object retrieval, anonymous direct denial, and absence of List/Put/Delete.
5. Keep the old pair available only for the bounded rollback window, then revoke it in RAM and securely remove the old files.
Rollback: atomically restore both previous Secret files and recreate only the Adapter. Never put either AccessKey value in Compose environment variables.
## TLS certificate
Renew the certificate/key outside Git, validate the full Nginx configuration, reload Nginx, and verify certificate chain/hostname/expiry. Rollback by restoring the previous certificate pair and reloading. Adapter containers do not receive TLS private keys.
## Rotation evidence
For every credential class, record only:
- change ticket/time;
- credential identity or role name, never value;
- old/new activation state;
- exact candidate image/config revision;
- sanitized health and E2E result;
- rollback result or rollback-window expiry.
+114
View File
@@ -0,0 +1,114 @@
# Security Model
## Security objectives
1. Keep the OSS bucket Private while permitting stable customer-facing UUID image links.
2. Keep all raw API keys, database credentials, OSS AccessKeys, object keys, and Presigned URL query parameters out of Git and logs.
3. Restrict retrieval to configured knowledge bases and image signing to active Adapter mappings.
4. Fail closed when validation, a database, WeKnora, OSS credential files, or signing is unavailable.
## Credential model
Because the target ECS instances are not permitted to receive RAM roles, the Adapter uses a dedicated RAM user's static AK. Test and production use different identities and different Private OSS buckets. The AccessKey ID and secret are mounted as separate read-only files; they are never accepted as Compose environment values, build arguments, API fields, or command-line arguments.
The production RAM user policy grants only `oss:GetObject`. Alibaba Cloud documents `oss:GetObject` as the permission required to download an object.[4] The supplied policy narrows this action to:
```text
acs:oss:*:*:${OSS_BUCKET}/weknora/${WEKNORA_TENANT_ID}/*
```
It intentionally omits List, Put, Delete, ACL, bucket-management, RAM management, and KMS permissions. A higher-privilege test AK may be used only for the explicitly approved test window; it must never be copied to production and must be replaced by a dedicated read-only identity before production traffic. If the reviewed bucket uses SSE-KMS, do not add `kms:Decrypt` automatically; review a separately scoped KMS policy first.
## Private OSS and temporary access
A V4 Presigned GET URL grants temporary access to one object without requiring credentials at the recipient.[2] V4 URLs expose `x-oss-expires`, use `OSS4-HMAC-SHA256`, and carry a signature in the query string.[2] Therefore:
- the URL lifetime is fixed at 600 seconds;
- the generated scheme and hostname are revalidated as the configured public regional OSS host;
- the URL appears only in the 302 `Location` header;
- the response is `no-store` and `no-referrer`;
- the URL is never persisted or logged;
- a stable `/i/{UUID}` remains reusable after the temporary URL expires.
The bucket must remain Private. Anonymous direct OSS access must return denial during Slice 9 acceptance.
## Secret storage
Raw secrets are mounted as read-only files owned by container UID 10001 with mode `0400`:
- `/run/secrets/weknora_api_key`
- `/run/secrets/asset_database_url`
- `/run/secrets/weknora_readonly_database_url`
- `/run/secrets/oss_access_key_id`
- `/run/secrets/oss_access_key_secret`
They must not appear in `.env`, Compose environment, Docker build args, image layers, source, fixtures, documentation examples, or shell command history. Dify stores only current/next SHA-256 hashes in non-secret runtime configuration.
## Input and SSRF controls
The Adapter does not perform arbitrary HTTP/HTTPS downloads. Callers cannot provide bucket, endpoint, object key, expiry, or destination URL. Only canonical `resource://` handles are accepted for first resolution; fixed tenant, storage backend, provider, bucket, and object-key rules are checked before persistence or signing.
This removes the general outbound URL-fetch primitive that would create SSRF risk. Outbound application destinations are limited to configured WeKnora, PostgreSQL, and the SDK-derived regional OSS endpoint.
## Authentication and authorization
- `POST /retrieval` requires a Dify Bearer key matching current or next hash.
- Requested knowledge bases must be allowlisted before search.
- Every returned chunk must repeat the requested knowledge-base UUID.
- `GET /i/{UUID}` is intentionally anonymous; possession of a valid UUID grants access.
- Missing and disabled UUIDs have the same empty 404 behavior.
- `GET /healthz` discloses only `{"status":"ok"}`.
## Logging and error redaction
The application writes one JSON request summary with only:
- request ID;
- method;
- matched route template;
- status code;
- duration in milliseconds;
- fixed error code for failures.
The following are prohibited from application and Nginx access logs:
- Dify or WeKnora API Key;
- `Authorization` header;
- request query/body and complete knowledge content;
- `resource://` locator;
- `object_key`;
- database DSN;
- OSS AccessKey ID/secret;
- Presigned URL or signature fields.
Nginx access logging is disabled for this virtual host. Unexpected exceptions return a fixed 500 without traceback or exception text in Adapter request logs.
## Container and network controls
- runtime UID/GID 10001; no root process;
- read-only root filesystem and no-exec temporary filesystem;
- all Linux capabilities dropped;
- `no-new-privileges` enabled;
- process, CPU, and memory limits set;
- Adapter published only on loopback;
- TLS 1.2/1.3 terminated by host Nginx;
- route/method allowlists, request-size limit, and rate limits at Nginx;
- Uvicorn raw access log disabled.
## Review checklist
- [ ] Private bucket confirmed; anonymous object GET denied.
- [ ] Dedicated test/production RAM users and AccessKeys are separate.
- [ ] Production RAM policy has only `oss:GetObject` for the reviewed bucket/tenant prefix.
- [ ] No other policy grants overlapping OSS write/list access.
- [ ] Five Secret files are owned by UID 10001 and mode `0400`.
- [ ] Adapter DB and WeKnora DB use different least-privilege accounts.
- [ ] Nginx certificate paths and public hostname are reviewed.
- [ ] Sanitized logs contain request IDs but none of the prohibited values.
- [ ] Arbitrary URL, bucket, object-key, and endpoint override tests pass.
- [ ] Slice 9 real test-environment E2E and audit report are accepted.
## Sources
[2] https://alibabacloud.com/help/en/oss/developer-reference/python-download-using-a-presigned-url — Alibaba Cloud OSS Python presigned GET URL
[4] https://www.alibabacloud.com/help/en/oss/developer-reference/get-object — Alibaba Cloud OSS GetObject permission
+107
View File
@@ -0,0 +1,107 @@
{
"executed_at": "2026-09-01T02:32:40.311192+00:00",
"execution_note": "真实请求通过公网HTTPS域名进入测试入口,再到测试ECS Nginx、Adapter和WeKnora。",
"endpoint": "https://weknora-api-test.dobot.cn/retrieval",
"request": {
"method": "POST",
"headers": {
"Authorization": "Bearer [REDACTED]",
"Content-Type": "application/json",
"Accept": "application/json",
"X-Request-ID": "frontend-public-api-sample"
},
"body": {
"knowledge_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"query": "接线",
"retrieval_setting": {
"top_k": 5,
"score_threshold": 0.2
}
}
},
"response": {
"status": 200,
"headers": {
"content-type": "application/json",
"x-request-id": "frontend-public-api-sample"
},
"record_count": 5,
"stable_image_uuid_count": 15,
"body": {
"records": [
{
"content": "与末端AI摄像头进行通信。\n\n![](https://weknora-api-test.dobot.cn/i/02e269e8-c4f0-4b3f-a41e-82f5b222a31f) \n图 3.4 Magic Box 侧面接线图\n\n## 3.1.2Magician Lite 接线说明\n\nMagician Lite需要单独购买,并将Magician Lite放置在Magician Go的机械臂安装槽内。机械臂安装槽内有1根10 Pin通信线和1根4 Pin电源线,用于连接Magician Lite的接口。\n\n![](https://weknora-api-test.dobot.cn/i/36a91564-9225-43fc-9fbf-b5ab226e22d6)\n\n请在设备完全断电的情况下进行接线。\n\n• 将Magician Lite的12V电源接口①与Magician Go的4 Pin电源线③连接,用于为Magician Lite供电。\n\n• 将Magician Lite的通信接口②与Magician Go的10 Pin通信线④连接,用于MagicBox与Magician Lite进行通信。\n\n![](https://weknora-api-test.dobot.cn/i/1e1743bb-e25c-4fe5-b1f0-ad861216e6dd) \n图 3.5 Magician Lite 接线图\n\n## 3.1.3 末端 AI 摄像头接线说明\n\n末端AI摄像头需要安装在Magician Lite上使用。在Magician Go的机械臂安装槽有1根4Pin摄像头通信线,出厂时已经装配到MagicianGo上,用于连接末端AI摄像头。\n\n注意\n\n请在设备完全断电的情况下进行接线。\n\n步骤1使用1.5mm内六角扳手松开AI摄像头套件的螺丝,如图3.6所示。\n\n![](https://weknora-api-test.dobot.cn/i/b8842b11-d3bb-4f82-aae3-82a59178d898)",
"score": 0.5314404987902756,
"title": "Dobot Magician Go用户手册V1.1_20240624_cn.pdf",
"metadata": {
"knowledge_base_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"knowledge_id": "3c878f4e-bfea-4c5c-b122-b63ba9db4e34",
"chunk_id": "d674ba02-7769-4e9a-8596-961cb50e1f75",
"chunk_index": 53,
"chunk_type": "text"
}
},
{
"content": "![](images/84d8ba268e5bbc1bb09ecf06a574dab30b21f3c9a7c426a2720ec688e715d2d6.jpg)\n\n:机械臂的通讯线端子接入控制柜的CAN接口(①),机械臂的电源线端子接入控制柜的电源接口(②),拧紧接线端子的螺丝。\n\n## 步骤3 连接电源\n\n将电源的接线端子接入控制柜电源接口(③)的V+/V-端。\n\n## 步骤4连接急停开关\n\n将急停开关连接至控制柜的急停开关接口(④),拧紧接线端子的螺丝。\n\n## 步骤5 连接市电\n\n将电源的市电插头接入市电插座。\n\n![](images/558d9e43126be73a5cd7fa1505faf124b63ea0dbc8d79e0ec0878ec5d68c5221.jpg)\n\n:请完成全部接线并确认接线无误后,再接通电源。\n\n## 步骤6 (选配)连接无线接收器\n\n将无线接收器接入控制柜的USB接口(⑤)。\n\n## 注意\n\n•设置外部配线的规格和安装方式应符合当地配电法规的要求。\n\n•请勿自行拆卸机器人,否则可能导致漏电。\n\n• 请确认设备接地良好。\n\n•请勿过度弯曲线缆,否则可能导致接触不良或断线。\n\n连接外部设备时请确认控制系统的电源插座已断开。如果未断开,可能导致触电或设备故障。\n\n•为了保护设备和人身安全,请使用配套的线缆。\n\n•接线完成后请确认设备内无掉落的螺钉或裸露线缆。\n\n•设备正常运行过程中,请勿随意插拔电源线缆及通信线缆。\n\n•必须将设备所需线缆连接完成后才能给设备通电。\n\n•请确认设备线缆连接正确,否则可能导致内部模块或外部设备故障。\n\n•连接前,检查外部电缆的绝缘及护罩是否破损。\n\n机械臂电源(②)和控制柜电源(③)线缆连接后,需要应用额外的保护措施,避免导线和接线端子直接裸露在外,且接线端子不能承受直接的应力。\n\n## 7.5 开机调试\n\n",
"score": 0.5292120593766394,
"title": "DOBOT 新款 Nova系列硬件使用手册.pdf",
"metadata": {
"knowledge_base_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"knowledge_id": "f76a4398-97fe-4362-85ea-b5e40da53893",
"chunk_id": "cadac306-bb4c-4bbf-b03b-69eb35ae9d7b",
"chunk_index": 106,
"chunk_type": "text"
}
},
{
"content": "<table><tr><td rowspan=1 colspan=1>接口</td><td rowspan=1 colspan=1>参数</td><td rowspan=1 colspan=1>最小值</td><td rowspan=1 colspan=1>典型值</td><td rowspan=1 colspan=1>最大值</td><td rowspan=1 colspan=1>单位</td></tr><tr><td rowspan=1 colspan=2>模拟输入(电压模式)</td><td rowspan=1 colspan=1></td><td rowspan=1 colspan=1></td><td rowspan=1 colspan=1></td><td rowspan=1 colspan=1></td></tr><tr><td rowspan=3 colspan=1>Alx</td><td rowspan=1 colspan=1>电压</td><td rowspan=1 colspan=1>0</td><td rowspan=1 colspan=1>1</td><td rowspan=1 colspan=1>10</td><td rowspan=1 colspan=1>V</td></tr><tr><td rowspan=1 colspan=1>电阻</td><td rowspan=1 colspan=1>1</td><td rowspan=1 colspan=1>14.7</td><td rowspan=1 colspan=1>1</td><td rowspan=1 colspan=1>kΩ</td></tr><tr><td rowspan=1 colspan=1>分辨率</td><td rowspan=1 colspan=1>1</td><td rowspan=1 colspan=1>12</td><td rowspan=1 colspan=1>1</",
"score": 0.5136077357877354,
"title": "Dobot Nova系列(适配DSC)硬件使用手册.pdf",
"metadata": {
"knowledge_base_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"knowledge_id": "2ca9b86e-43d6-47cd-b519-727a4333dae8",
"chunk_id": "51963bfd-2514-458a-8e59-51b17e571d56",
"chunk_index": 95,
"chunk_type": "text"
}
},
{
"content": " \n机器人控制柜 \n焊机通讯模块和网关之间的线缆请按照设备上显示的接口定义对应连接。\n\n## 2.2.3 连接验证\n\n硬件连接完成后,可在焊接插件中完成焊机匹配后,使用手动送丝/退丝功能验证通讯是否正常。\n\n## 2.3 模拟通讯\n\n## 2.3.1 准备工作\n\n下图为焊接插件中需配置的I/O信号,请先根据现场需求进行规划:\n\n①控制柜信号:必须配置。\n\n②接触寻位信号/③其他信号/④弧焊模板信号:根据实际业务需求配置。\n\n信号的含义请参考基础焊接信号配置和接触寻位信号配置。\n\n![](https://weknora-api-test.dobot.cn/i/f6617db7-c032-4ae4-b67c-4f06ed5ccb0e) \n然后,请根据规划准备信号线。\n\n•模拟信号线x3,为提高模拟信号的精度,建议使用屏蔽线或双绞线。\n\n• 数字信号线,数量根据I/O 规划决定。\n\n## 2.3.2 10 接线\n\n连接控制柜模拟信号接口与对应的焊机模拟通讯接口。\n\n![](https://weknora-api-test.dobot.cn/i/034166a0-67fa-4e6b-b628-876a9072e159)\n\n## i说明\n\nCloos 焊机无需连接模拟信号,但需要额外连接DO1\\~DO8 至焊机用于指定Job号,具体接线说明请参考以下章节:Cloos焊机。\n\n此外还需连接数字通讯接口。控制柜侧的数字接口可在插件中配置,下图的接线方式仅供参考。\n\n用户手册\n\n![](https://weknora-api-test.dobot.cn/i/34bdd865-b1d5-4783-a718-9da865e9a85d)\n\n焊机侧的接线请参考焊机说明书。下文以奥太AMIGPR系列为例简单介绍。奥太AMIGPR系列焊机的模拟通讯接口及引脚序号如下图所示。 \n![](https://weknora-api-test.dobot.cn/i/74ed882a-822d-46ce-a5c4-6ccb22366b08)\n\n引脚定义和对应的机械臂控制柜侧接口如下表所示(数字信号均为NPN型)。\n",
"score": 0.49706713450175893,
"title": "DOBOT 焊接工艺包用户手册.pdf",
"metadata": {
"knowledge_base_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"knowledge_id": "d212c8d9-5bd4-43bd-8316-5f2d9168dd2b",
"chunk_id": "3fcd2242-cf69-4619-8be3-95c1b05f6667",
"chunk_index": 38,
"chunk_type": "text"
}
},
{
"content": "\n\n4.连接相机线缆,连接方法与全局相机相同。\n\n## 注意\n\n相机和主手机械臂要连接在不同的USB hub上,且相机的USB hub要连接在电脑的USB 3.0接口上。\n\n●确保相机线缆连接到位,避免因相机接触不良造成后续数据采集异常。\n\n## 2.3.8 连接散热风扇\n\n工作台柜体中自带一个散热风扇,如需使用,请将该风扇的电源线连接至电控柜的24V电源输出,红色线接24V接口,黑色线接0V接口。\n\n![](https://weknora-api-test.dobot.cn/i/43a53773-93cb-433d-adc0-375fdf612821) \n风扇\n\n![](https://weknora-api-test.dobot.cn/i/909f9735-d7ab-4596-af3d-cef504da47c4)\n\n## 2.3.9 连接指示灯\n\n指示灯出厂时已安装在底座上。使用指示灯连接线连接指示灯和从手1控制器。连接控制器时注意对齐线标和控制器上的丝印,接线后线缆应集中在端子左侧。\n\n![](https://weknora-api-test.dobot.cn/i/d90e850e-0388-4535-b642-33919cb41f89)\n\n## 2.3.10 连接训练主机\n\n使用网线连接训练主机和电控柜。\n\n![](https://weknora-api-test.dobot.cn/i/6a415304-6fe0-4bee-8c6e-74f5ae1770a7) \n电控柜\n\n## 2.3.11 整理线缆\n\n安装接线完成后,建议参考下图,使用发货附件的魔术贴(发货时为一整卷,需用户自行裁剪)将夹爪和相机线缆固定在从手上,避免从手运动时拉扯线缆。\n\n![](https://weknora-api-test.dobot.cn/i/bbc83287-1251-4d4e-87e4-c84bd4b62ddd) \n发货附件中还包含一包塑料扎带,用户可用于整理其余线缆。\n\n## 2.3.12 设备上电\n\n## 主手上电\n\n主手的电源开关位于底座,按下开关即可上电。上电状态下按下开关即可下电。\n\n![](https://weknora-api-test.dobot.cn/i/ed57e0bf-61d5-4d8a-b4c2-d3af02552bcf)\n\n## 从手上电\n\n从手的电源开关位于控制器(CCBOX)上,短按开机,长按(3s以上)关机。\n\n![](https://weknora-api-test.dobot.cn/i/7ff587e1-f4b6-4706-81bb-7e39b9fd8047)",
"score": 0.49572175212959224,
"title": "Dobot X-Trainer(完整版)_用户手册_cn.pdf",
"metadata": {
"knowledge_base_id": "b9dacd62-87eb-4b38-a6b6-85f68e144796",
"knowledge_id": "11dcd67e-770b-4387-ba87-3357a6c16c25",
"chunk_id": "7f52676c-a6f6-4663-b643-c5308a67e53f",
"chunk_index": 38,
"chunk_type": "text"
}
}
]
}
},
"image_e2e": {
"stable_url": "https://weknora-api-test.dobot.cn/i/02e269e8-c4f0-4b3f-a41e-82f5b222a31f",
"stable_uuid_status": 302,
"cache_control": "no-store",
"referrer_policy": "no-referrer",
"signed_location_recorded": false,
"signed_image_status": 200,
"content_type": "image/jpeg",
"bytes": 56025,
"sha256": "a0f2b91c84daf1b31585d3b09f0d0a518fad9fabc5b06f0406bb509cd830fb9b",
"format_signature_valid": true
}
}