---
title: Ax9000WRTBuild – Troubleshooting Guide (shared usage profile)
type: curated
permalink: main/projects/6f47523e-e22e-4cdd-bd18-76e5e474ee0c/curated/development/ax9000-wrtbuild-troubleshooting-guide-shared-usage-profile
stable_id: 468f52a6-e941-49f7-a422-64bbcec6e0f4
scope: project
project_id: 6f47523e-e22e-4cdd-bd18-76e5e474ee0c
workspace_type: general
usage_profile_id: null
preference_context: general
document_type: troubleshooting
revision: 1
source_memory_ids: []
source_checkpoint_ids: []
source_file_ids: []
source_git_commit: c62e79c3b986262321aa4242f0ece56c4629ae0e
source_git_commits:
- c62e79c3b986262321aa4242f0ece56c4629ae0e
source_agent_sync_ids: []
model_connection: Sub2API
model_name: git-restore
source_count: 81
source_revisions: {}
source_dispositions:
  processed: 81
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids: []
job_cited_source_ids: []
conflicts: []
supersedes: []
preferences: []
source_cursor: 13
source_hash: a3dc8f049fcd5e54d4e2bc4b420c13cce749fadf5c3ca6178780171167541cf3
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: null
created_at: '2026-08-12T18:38:16.712653+00:00'
updated_at: '2026-09-23T14:59:04.601333+00:00'
tags:
- troubleshooting
- issues
- fixes
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

### 1. Docker Hub 代理失效
- **症状**：`docker pull` 报错，日志显示只能通过 `http://127.0.0.1:7897` 代理。
- **原因**：代理环境变量仅在 `docker run` 时传递，Docker Desktop 未设置为 *Manual proxy*。
- **解决方案**：在 Docker Desktop → Settings → Resources → Proxies 中选择 *Manual proxy*，填写 `http://127.0.0.1:7897`（任务 #1）。
- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`。

### 2. FastAPI 未认证
- **症状**：后端在 `0.0.0.0:9001` 无任何鉴权，外部网络可直接调用。
- **影响**：高危安全风险（任务 #2）。
- **解决方案**：在 `scripts/build_config.py` 中启用 `jwtAuth=true`，在 `web/server/main.py` 添加 JWT 中间件并绑定地址到 `127.0.0.1` 或局域网限定端口。
- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`, `67e34406-4966-4e48-ab88-69e2fb15a144`。

### 3. 明文凭据泄漏
- **症状**：`.runtime/*.json` 中出现真实密码。
- **解决方案**：在构建前运行 `scripts/install_external_packages.py` 的检查，将所有密码字段删除，仅保留 `name`、`purpose`、`usage`。所有运行时凭据改为 Vaultwarden 条目名，并在 `scripts/build.sh` 中立即写入 Vaultwarden（任务 #3）。
- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`, `105b328f-4bda-4641-90a7-7282ef156316`。

### 4. 非确定性构建
- **症状**：相同源码在不同机器生成的固件 SHA 不一致。
- **解决方案**：在 `build_config.py` 中固定 Docker 基础镜像摘要、所有 Git SHA、Python 锁文件（`requirements.txt`、`pyproject.toml`），并在 `scripts/build.sh` 的 `verify_final_config` 中检查这些锁定项（任务 #4）。
- **参考**：`67e34406-4966-4e48-ab88-69e2fb15a144`。

### 5. 脆弱的文本补丁
- **症状**：`patch_ax9000.py` 在源码升级后经常失败。
- **解决方案**：使用 `scripts/patch_feed_packages.py` 将补丁转换为标准 `.patch` 文件，改为 `git am` 应用（任务 #5）。
- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`, `67e34406-4966-4e48-ab88-69e2fb15a144`。

### 6. 配置漂移（UI 与模型不同步）
- **症状**：LuCI UI 中的选项与后端生成的 JSON‑Schema 不一致。
- **解决方案**：在 `scripts/build_config.py` 中统一使用单一 `package-catalog.json` 生成 Pydantic 与 TypeScript 类型，确保 UI 与模型同步（任务 #7）。
- **参考**：`da185d9b-8e7f-442f-b329-5bd345ab3e07`, `468f52a6-e941-49f7-a422-64bbcec6e0f4`。

### 7. 日志未持久化
- **症状**：构建期间的日志仅保存在容器内存，构建结束后丢失。
- **解决方案**：在 `push_log` 中将日志缓冲写入 `outputs/ax9000/logs/$(date).log`，并在 `scripts/build.sh` 完成后复制至持久化卷。
- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`。

**所有上述问题对应的修复已列入任务列表（文档 *tasks*）**。