Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
198 lines (138 loc) · 9.09 KB

TROUBLESHOOTING.md

File metadata and controls

198 lines (138 loc) · 9.09 KB
Raw

Troubleshooting

HF Space 显示 NO_APP_FILE

说明 Space repo 里没有有效 Dockerfile，或者 README metadata 没有正确声明 sdk: docker。检查：

hf spaces info BlueSkyXN/Coze-all-in-one-HFS
git ls-remote https://huggingface.co/spaces/BlueSkyXN/Coze-all-in-one-HFS refs/heads/main

Runtime manifest 或 artifact bootstrap 失败

COZE_RUNTIME_MANIFEST_URI 必须是无 query、fragment、嵌入凭据的 https://huggingface.co/... URL。启动只允许同域 huggingface.co 中间跳转或 Hugging Face 的 *.xethub.hf.co Xet 下载跳转；Bearer 只在同域保留，进入 Xet 下载域前移除，其他跳转一律拒绝。manifest 仍须包含完整 40 位 commit、按同一 commit 命名的 BUILD_SOURCE-<commit>.json SHA-256、server/web artifact SHA-256 与 size。检查顺序：

  1. 用 scripts/verify-runtime-artifacts.py --manifest <manifest> --artifacts-dir <dir> 在发布前复验 Release 文件。
  2. 确认 manifest、commit-named BUILD_SOURCE-<commit>.json、server 和 web 已 artifact-first 上传并逐字节 readback；manifest 必须最后写入。
  3. 若下载面私有，确认 COZE_RUNTIME_DOWNLOAD_TOKEN 仅作为 Space Secret 存在；Bearer 只发送给 huggingface.co，不会转发到 Xet 下载域，也不要把 token 放 URL。
  4. 从受 OPS_TOKEN 保护的 /_ops/version 回读 source commit、manifest checksum 和 artifact checksums，不要从日志或 URL 查 token。

不允许通过旧 /app、缓存、目录扫描、latest 或备用 URI 让容器继续启动。COZE_SOURCE_COMMIT 同时绑定 schema、Atlas HCL 与 server/web runtime artifact；COZE_RELEASE_TAG=v0.5.1 仅是描述性 label，不能替代 commit provenance。

DB schema import fails

当前本地数据库层是 MariaDB。官方 Coze Compose 使用 MySQL 8.4.x。如果 schema 使用 MariaDB 不兼容语法，下一步选项是：

  1. 外接 MySQL-compatible 服务。
  2. 改造 runtime 使用 MySQL 官方二进制或 MySQL-compatible 镜像组装层。
  3. 临时 pin 到已验证可导入的 Coze tag。

不要直接删 schema 或跳过 DB migration 后声称调通。

/_ops/healthz 返回 503

读取 JSON 中的 checks：

curl -fsS https://blueskyxn-coze-all-in-one-hfs.hf.space/_ops/healthz

常见含义：

  • mariadb=false：DB 初始化失败或 datadir 权限异常。
  • redis=false：Redis 未启动，检查 Supervisor logs。
  • nats=false：NATS JetStream 未启动，检查 /data/coze/nats 权限。
  • minio=false：本地 MinIO fallback 未启动；如果 ENABLE_LOCAL_MINIO=0，ops 不检查本地 MinIO，但内置 Milvus 仍需要可访问的外部 MINIO_ADDRESS。
  • etcd=false：Milvus 依赖的 etcd 未启动。
  • elasticsearch=false：ES 未启动或 analysis-smartcn / index template 初始化失败。
  • milvus=false：Milvus standalone 未启动，先看 etcd/MinIO 依赖；如果日志出现 libaio.so.1、libgomp.so.1 或 libopenblas.so.0，说明 final image 缺 Milvus runtime 动态库。
  • coze_server=false：Coze Server 未监听 8888，继续看 ES、VectorStore、DB 或 model 初始化错误；如果日志出现 /app/runtime/opencoze: cannot execute: required file not found，说明 Alpine/musl ABI 的 Coze server 二进制缺动态加载器。

如果已配置 OPS_TOKEN，继续查看只读诊断面：

curl -H "X-Ops-Token: $OPS_TOKEN" \
  https://blueskyxn-coze-all-in-one-hfs.hf.space/_ops/processes
curl -H "X-Ops-Token: $OPS_TOKEN" \
  "https://blueskyxn-coze-all-in-one-hfs.hf.space/_ops/logs?service=coze-server&lines=200"
curl -H "X-Ops-Token: $OPS_TOKEN" \
  https://blueskyxn-coze-all-in-one-hfs.hf.space/_ops/errors

/_ops/logs 只能读取 /data/coze/logs 下的白名单日志；不能用它读取任意路径、secret 文件或 .env.local。

/_ops/ 返回 401 或 503

  • 401：未提供有效 OPS_TOKEN。CLI 使用 X-Ops-Token 或 Authorization: Bearer。
  • 503：OPS_TOKEN 未设置或少于 24 字符。

浏览器直接打开：

/_ops/

在页面中输入 OPS_TOKEN。服务明确拒绝 ?token=；不要把 secret 放进 URL、浏览器历史或 Nginx access log。刷新页面后需要重新输入，这是有意的非持久化认证边界。

/_admin/ 返回 404

这是默认安全状态：ADMIN_ENABLED=false。确需短期开启时设置：

ADMIN_ENABLED=true
ADMIN_TOKEN=<at-least-24-random-characters>

ADMIN_TOKEN 不能复用 OPS_TOKEN。admin service 使用独立 cozeadmin OS user，默认 audit 路径是 /data/coze/admin/audit.jsonl。

开启后用 smoke 验证：

ADMIN_EXPECTED_ENABLED=true \
ADMIN_TOKEN=$ADMIN_TOKEN \
./scripts/admin-smoke.sh https://blueskyxn-coze-all-in-one-hfs.hf.space

公开 Space 不建议长期开启 admin。/_admin 只支持白名单 action、confirm=true、cookie CSRF 和 audit，不提供 Web terminal、任意 shell command、SQL 执行或 secret rotation。

/admin 或 /api/admin/* 返回 404

这是 Coze v0.5.1 的临时安全 guard，不是 Nginx 路由遗漏。该版本的 upstream admin middleware 在 admin email 为空时会 fail-open；wrapper 在匹配的 upstream 修复版 server/web 镜像发布前阻断内置 admin UI/API。运行策略通过 HF Variables/Secrets 和 /app/runtime/.env 管理，不要绕过该 guard。

登录或注册被拦

公开 Space 默认关闭注册：

DISABLE_USER_REGISTRATION=true

ALLOW_REGISTRATION_EMAIL 在 Coze v0.5.1 fresh fallback config 中存在 upstream 读取缺陷，且不属于 clean no-paid manifest。不能以空值或示例邮箱同步，也不能只凭 env 值声称 allowlist 已生效。受控测试可以临时设置：

ALLOW_REGISTRATION_EMAIL=you@example.com

设置后仍需执行真实注册 smoke；不要在公开文档、PR 文案或截图里写真实邮箱、账号或密码。

Code runner 不在 sandbox

生成的 /app/runtime/.env 应包含：

CODE_RUNNER_TYPE=sandbox
CODE_RUNNER_ALLOW_NET=cdn.jsdelivr.net

Coze v0.5.1 对空值会回退到 local runner。本 wrapper 已显式覆盖为 sandbox；如果手动设置 CODE_RUNNER_TYPE=local，属于明确降低隔离级别的操作。静态 env 检查不能替代真实 workflow code-node smoke，尤其要确认 user 的 HOME=/home/user 下 Deno/Pyodide 首次加载成功。

模型不可用

clean no-paid profile 故意不登记模型/provider Variables；它可以启动页面和本地基础服务，但不会启用文本 Agent 的模型调用。需要模型能力时，应建立完整的 provider-enabled 配置，而不是向 clean profile 写入空值或占位值：

MODEL_PROTOCOL_0
MODEL_OPENCOZE_ID_0
MODEL_NAME_0
MODEL_ID_0
MODEL_BASE_URL_0
MODEL_API_KEY_0
BUILTIN_CM_TYPE
BUILTIN_CM_OPENAI_BASE_URL
BUILTIN_CM_OPENAI_API_KEY
BUILTIN_CM_OPENAI_MODEL

API key 必须放 HF Secrets。Base URL 如果包含私有网关、租户或 token，也按 Secret 管理。

/data/coze 没有持久化

HF models、datasets 和 spaces volume 是只读挂载；Coze 数据目录必须使用 read-write bucket volume。挂载后设置：

PERSISTENCE_REQUIRED=true

如果 /_ops/healthz 返回 checks.persistent_data=false，说明 /data/coze 没有作为独立 mount 生效。不要关闭门禁后继续写 overlay filesystem；应检查 hf spaces volumes list 和 bucket 权限。

注意：bucket 挂载不支持 unix socket（MariaDB 报 Bind on unix socket: Function not implemented）。runtime socket/PID 固定在容器内 RUN_DIR（默认 /run/coze），不要把这些路径指回 /data/coze。

bucket 挂载上的 IO 比本地盘慢，Milvus proxy 就绪时间会变长。Coze Server 对 Milvus Proxy is not ready yet 是直接 panic 而非重试，因此 run-coze-server.sh 在 TCP 等待之外还会等 http://127.0.0.1:9091/healthz 真正就绪；不要删掉这层 readiness gate。

持久化 etcd 会跨容器保留 Milvus 的 session 注册，新容器启动时组件会去拨上一任容器的 IP（dial tcp 10.x.x.x:53100: i/o timeout）并退出。run-milvus.sh 启动前会清理 by-dev/meta/session 前缀（session 本来就是 lease 临时状态），不要改成持久化这些注册。

文件上传 URL 模型不可读

clean no-paid profile 默认使用 STORAGE_TYPE=minio 和本地 MinIO，不需要 S3 endpoint/region Variables。本地 MinIO fallback 只为 P0/P1 演示保留；真实上传、多模态或模型可读 URL 建议建立完整的 S3/TOS/ImageX 扩展配置：

FILE_UPLOAD_COMPONENT_TYPE=storage
STORAGE_TYPE=s3
S3_ACCESS_KEY
S3_SECRET_KEY
S3_ENDPOINT
S3_BUCKET_ENDPOINT
S3_REGION
STORAGE_BUCKET

Knowledge/RAG 初始化失败

Coze 启动阶段会初始化 ES 和 Vector Store。clean no-paid profile 默认使用 ES_ADDR=http://127.0.0.1:9200 与 VECTOR_STORE_TYPE=milvus，不需要 VikingDB endpoint Variables；若改用外部托管服务，再建立完整的 HF Variables/Secrets 扩展配置：

ES_ADDR
ES_VERSION
ES_USERNAME
ES_PASSWORD
VECTOR_STORE_TYPE
VIKING_DB_HOST
VIKING_DB_REGION
VIKING_DB_AK
VIKING_DB_SK
VIKING_DB_SCHEME
OPENAI_EMBEDDING_BASE_URL
OPENAI_EMBEDDING_MODEL
OPENAI_EMBEDDING_API_KEY