85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
---
|
||
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*）**。 |