@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/_packed_docs/aun/345/205/254/347/275/221/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -0,0 +1,234 @@
+# AUN 公网测试运行指南
+
+本文说明如何对 `evolagent.cn`、`agentid.pub` 或同拓扑的其他公网 issuer domain 运行 Python SDK integration/E2E。公网测试与本地 Docker 单域、分布式 `data-dist` 完全分离，不复用其身份、临时文件或报告目录。
+
+## 测试指南:
+D:\modelunion\kite\aun-sdk-core\docs\aun测试运行指南.md
+D:\modelunion\kite\aun-sdk-core\docs\aun分布式测试运行指南.md
+D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
+
+运行测试(单元、集成、E2E, cross-sdk, 双域)时应该使用断点续跑的方法，即运行到某个测试时如果发生失败，应该立即停下来，修复此用例，然后再接着此用例运行后续用例。之前通过的用例如果手续修改不受影响则不要重复跑。
+
+## 1. 测试入口与边界
+
+Python SDK 公网入口：
+
+```text
+python/run-public-tests.py
+```
+
+它只编排可通过公网协议完成的 SDK 用例，不读取服务端 MySQL/Redis，不操作 Docker 网络，也不重启远端服务。公网 `full` 覆盖 50 个去重后的 integration/E2E，用例按顺序逐个在独立子进程中运行。
+
+服务端主要模块的公网验收入口另为：
+
+```text
+../docker-deploy/tests/public_single_instance_acceptance.py
+```
+
+该脚本补充 AUN Console、Leaderboard、AID Custody、服务注册状态和端口/TLS 等服务端检查。它与 SDK runner 不是重复关系，完整验收时应先跑服务端验收，再跑 SDK `smoke` 或 `full`。
+
+## 2. 数据隔离
+
+SDK runner 默认只使用仓库下的 `.public-test-data/`：
+
+```text
+.public-test-data/
+├── identities/<domain>/<identity-prefix>/
+│   ├── persistent/
+│   └── service-proxy-provider/
+└── runs/<domain>/<run-id>/
+    ├── logs/
+    ├── artifacts/
+    ├── tmp/
+    ├── home/
+    ├── pycache/
+    └── report.json
+```
+
+- `identities/` 跨运行保留测试私钥、证书和 token，避免每次重复注册固定测试 AID。
+- `runs/` 每轮独立保存日志、临时目录、HOME、CLI 状态和 JSON 报告。
+- 每个用例还有独立的 `HOME`、`TEMP/TMP/TMPDIR`、CLI 配置和 Python bytecode 目录。
+- runner 默认串行执行，避免同一测试身份的槽位、在线状态和游标相互干扰。
+
+runner 会拒绝与下列目录重叠的数据根：
+
+- `../docker-deploy/data`
+- `../docker-deploy/data-aun-pub`
+- `../docker-deploy/data-evolagent-cn`
+- `../docker-deploy/federation-test/data-dist`
+- 仓库中的旧 `.aun*`
+- 用户真实的 `~/.aun`
+
+服务端公网验收建议使用 `../docker-deploy/public-test-data/` 和 `../docker-deploy/public-test-artifacts/`，不要与 SDK 的 `.public-test-data/` 混用。
+
+## 3. 前置条件
+
+- 目标域的公网 DNS、证书和服务端口已配置完成。
+- Python 3.11 以上；推荐使用已构建的 `aun-sdk-tester:latest` 容器。
+- 目标至少可访问 NameService 443、Gateway 20001、Storage 9470、Group 9480、Stream 9490 和 Service Proxy 19890。
+- 用于新身份的加密 seed 通过环境变量 `AUN_TEST_ENCRYPTION_SEED` 注入；同一 `identity-prefix` 后续必须使用同一个 seed。
+- 公网测试会创建 AID、消息、群、对象、agent.md 和 Service Proxy 注册，不能使用真实用户 AID。
+
+实际执行必须显式传入 `--allow-create-identities`。遗漏该参数时 runner 会在联网前退出；`--list` 和 `--dry-run` 不需要该确认。
+
+## 4. 先检查命令
+
+在 `aun-sdk-core/python` 目录执行：
+
+```powershell
+python -X utf8 run-public-tests.py --list
+python -X utf8 run-public-tests.py `
+  --domain evolagent.cn `
+  --suite full `
+  --identity-prefix public-ci `
+  --dry-run
+```
+
+`dry-run` 会验证域名、目录安全规则、用例名称和所有测试文件，只打印命令，不创建目录、不连接公网、不创建身份。
+
+切换域名只需修改 `--domain`：
+
+```powershell
+python -X utf8 run-public-tests.py --domain agentid.pub --suite smoke --dry-run
+```
+
+## 5. 推荐：在一次性 Docker 容器中运行
+
+以下 PowerShell 命令从 `aun-sdk-core` 根目录执行。容器使用默认 bridge 网络访问公网，不加入本地 `kite-net`，代码只读挂载，公网测试数据单独挂载：
+
+```powershell
+$repo = (Get-Location).Path
+$env:AUN_TEST_ENCRYPTION_SEED = "使用固定的公网测试 seed"
+
+docker run --rm `
+  -v "${repo}\python:/workspace/python:ro" `
+  -v "${repo}\.public-test-data:/public-test-data" `
+  -e AUN_TEST_ENCRYPTION_SEED `
+  -w /workspace/python `
+  aun-sdk-tester:latest `
+  python -X utf8 run-public-tests.py `
+    --domain evolagent.cn `
+    --suite smoke `
+    --data-root /public-test-data `
+    --identity-prefix public-ci `
+    --allow-create-identities `
+    --fail-fast
+```
+
+确认 `smoke` 通过后，把 `--suite smoke` 改成 `--suite full`。Linux/macOS 使用相同挂载关系，将 PowerShell 续行符替换为 `\` 即可。
+
+## 6. 宿主机直接运行
+
+宿主机已安装当前 Python SDK 依赖时，可在 `aun-sdk-core/python` 下执行：
+
+```powershell
+$env:AUN_TEST_ENCRYPTION_SEED = "使用固定的公网测试 seed"
+python -X utf8 run-public-tests.py `
+  --domain evolagent.cn `
+  --suite full `
+  --identity-prefix public-ci `
+  --allow-create-identities
+```
+
+可用 `--data-root D:\aun-public-tests` 改变公网数据根，但仍会经过受保护目录重叠检查。
+
+## 7. 套件矩阵
+
+| 套件 | 用例数 | 主要范围 |
+| --- | ---: | --- |
+| `smoke` | 9 | Auth/Gateway token、CA 指纹、Message ACK、Group 管理/index、Storage、Stream、Echo、Service Proxy |
+| `integration` | 28 | 消息、群、Storage/FS、Stream、NameService、Collab、签名、同步与失败契约 |
+| `e2e` | 23 | Echo/trace/refresh、V2 E2EE、多设备、thought、Group FS、CLI FS、Collab、Notify、Service Proxy |
+| `full` | 50 | `integration + e2e` 去重；不自动包含压力测试 |
+| `stress` | 3 | Gateway quota、slot-id storm、长短连接 CLI 压力 |
+
+`full` 的主要业务覆盖：
+
+- Auth/CA/Gateway：身份注册、认证、token/Gateway 缓存复用、正式 refresh、PKI DER/SPKI 指纹、长短连接和 quota。
+- Message：P2P 明文/E2EE、ACK、在线状态、notify、replay guard、失败路径、push seq、gap fill、inbox、thought、多设备。
+- Group：生命周期、角色、邀请/审批/封禁、设置、搜索、撤回、游标同步、在线未读、签名审计和 `group.index`。
+- Storage/Group FS/Collab：控制面与数据面、ACL、配额、分享、VFS P1-P4、CLI P1-P6、群目录及协作链路。
+- Stream：RPC、token、HTTP、SSE、WebSocket、回放、多拉流端和输入校验。
+- NameService：agent.md 上传、同步、认证边界和快照下载。
+- Service Proxy：公网发现、provider 隧道、HTTP/SSE/WebSocket 和并发访问。
+
+指定少量用例时可重复使用 `--case`；此时 `--case` 覆盖套件默认清单：
+
+```powershell
+python -X utf8 run-public-tests.py `
+  --domain evolagent.cn `
+  --case integration-message-ack `
+  --case e2e-v2-p2p `
+  --identity-prefix public-debug `
+  --allow-create-identities
+```
+
+## 8. 明确不纳入公网套件的用例
+
+- `e2e_test_group_index.py`：只是 `integration_test_group_index.py` 的包装入口，`full` 按同一 `group-index` 用例去重。
+- `integration_test_reconnect.py`：会操作 Docker 网络并重启 Gateway。
+- `integration_test_mail*.py`：当前公网单实例未启用 Mail/SMTP/IMAP/Mailpit。
+- `integration_test_p0_common_gaps.py`：包含 loopback 和本地故障注入。
+- `integration_test_service_proxy.py`：加载服务端源码并启动进程内本地服务；公网使用 `e2e_test_service_proxy_docker.py`。
+- `test_integration_auth_flow.py`：主要验证本地 mock CA/Gateway，不是公网 E2E。
+- `local_real_sms_e2e.py`：会调用真实短信网关，必须单独授权。
+
+这些排除项可通过 `--list` 查看，runner 不提供绕过开关，避免 `full` 意外影响本地容器或外部系统。
+
+## 9. TLS 规则
+
+公网 runner 固定设置 `AUN_ENV=production`、`KITE_ENV=production`，并默认启用控制面和数据面的证书校验。SDK、AIDStore、Storage、Stream、NameService 和 Service Proxy 使用同一测试 TLS 开关。
+
+只有临时测试域证书尚未就绪时才使用：
+
+```powershell
+python -X utf8 run-public-tests.py `
+  --domain temporary.example.com `
+  --suite smoke `
+  --insecure-skip-tls-verify `
+  --allow-create-identities
+```
+
+该运行会在 `report.json` 中记录 `verify_ssl: false`，不能作为正式公网 TLS 验收结果。
+
+## 10. 报告与排障
+
+每个用例实时输出到控制台，同时写入：
+
+```text
+.public-test-data/runs/<domain>/<run-id>/logs/<case>.log
+```
+
+整轮结构化结果位于：
+
+```text
+.public-test-data/runs/<domain>/<run-id>/report.json
+```
+
+常用参数：
+
+- `--run-id <id>`：固定本轮目录名；已存在且非空时拒绝覆盖。
+- `--timeout-seconds <n>`：每个用例独立超时，默认 1800 秒。
+- `--fail-fast`：首个失败或超时后停止，报告中的 `not_run` 会记录未执行数量。
+- `--identity-prefix <prefix>`：隔离不同域、人员或 CI 任务；固定角色会生成为 `<prefix>-alice.<domain>` 等 AID。
+
+失败时先查看对应 case 日志，再核对公网 DNS、证书 SAN、端口和 NameService 公告地址。切换域名后，不要复制另一个域的 identity 目录；应使用同一数据根下按 domain 自动分开的目录。
+
+## 11. 服务端公网验收
+
+SDK 测试前，可从 `aun-sdk-core` 根目录运行服务端验收：
+
+```powershell
+$repo = (Get-Location).Path
+$env:PYTHONPATH = "${repo}\python\src"
+$env:AUN_ACCEPTANCE_ENCRYPTION_SEED = "使用独立的服务端验收 seed"
+
+python -X utf8 ..\docker-deploy\tests\public_single_instance_acceptance.py `
+  --target-mode public `
+  --domain evolagent.cn `
+  --data-root ..\docker-deploy\public-test-data `
+  --artifact-root ..\docker-deploy\public-test-artifacts `
+  --allow-create-identities
+```
+
+该验收必须 12 项全部 PASS，重点补齐 SDK runner 不直接覆盖的 AUN Console、服务注册健康、Leaderboard 和 AID Custody。服务端验收与 SDK runner 使用不同默认 AID 和不同本地数据目录，可连续运行。