109 lines
4.6 KiB
Markdown
109 lines
4.6 KiB
Markdown
---
|
||
title: Common Issues & Troubleshooting Guide
|
||
type: curated
|
||
permalink: main/projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/common-issues-troubleshooting-guide
|
||
stable_id: 0f32d409-b512-4fc9-b65e-59d8a70359b8
|
||
scope: project
|
||
project_id: d1932ed6-07d3-4463-a224-8534ffd69a07
|
||
workspace_type: development
|
||
usage_profile_id: null
|
||
preference_context: development
|
||
document_type: troubleshooting
|
||
revision: 1
|
||
source_memory_ids: []
|
||
source_checkpoint_ids: []
|
||
source_file_ids: []
|
||
source_git_commit: 346195c0699cb8a1dbf5a9576daad945003e5d10
|
||
source_git_commits:
|
||
- 346195c0699cb8a1dbf5a9576daad945003e5d10
|
||
source_agent_sync_ids: []
|
||
model_connection: Sub2API
|
||
model_name: openai/gpt-oss-120b
|
||
source_count: 25
|
||
source_revisions: {}
|
||
source_dispositions:
|
||
processed: 25
|
||
unchanged: 0
|
||
unsupported: 0
|
||
skipped: 0
|
||
cited_source_ids:
|
||
- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
|
||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||
job_cited_source_ids:
|
||
- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
|
||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||
conflicts: []
|
||
supersedes: []
|
||
preferences:
|
||
- statement: AI 驱动的记忆同步与 Git 集成默认关闭
|
||
level: workspace
|
||
workspace_types:
|
||
- development
|
||
workspace_ids:
|
||
- d1932ed6-07d3-4463-a224-8534ffd69a07
|
||
source_ids:
|
||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||
counterexample_source_ids: []
|
||
occurrence_count: 1
|
||
explicit: true
|
||
confidence: 1.0
|
||
status: current
|
||
- statement: 日常交流使用中文（包括文档、代码注释等）
|
||
level: workspace
|
||
workspace_types:
|
||
- development
|
||
workspace_ids:
|
||
- d1932ed6-07d3-4463-a224-8534ffd69a07
|
||
source_ids:
|
||
- global_guidance_memory:7429c22e-50ff-458a-97c0-423c679904c7
|
||
counterexample_source_ids: []
|
||
occurrence_count: 1
|
||
explicit: true
|
||
confidence: 1.0
|
||
status: current
|
||
source_cursor: 292
|
||
source_hash: deb30a6b83a03f25e5a91c6b2d68024ae3de216638efb5597267ac9555bb804f
|
||
prompt_version: 2026-08-12.3
|
||
schema_version: '3'
|
||
curation_job_id: ef181130-6e65-470d-be87-1c06a2de345c
|
||
created_at: '2026-09-02T18:36:51.454085+00:00'
|
||
updated_at: '2026-09-02T18:36:51.454519+00:00'
|
||
tags:
|
||
- troubleshooting
|
||
- development
|
||
---
|
||
|
||
# 常见问题及排障指南 (Troubleshooting)
|
||
|
||
## 1. Docker 执行超时 (3 秒断连)
|
||
- **症状**：`docker exec` 长时间运行的命令在约 3 秒后被强制中止。
|
||
- **根因**：Docker‑Py 默认为 hijacked socket 设置了 3 秒的全局 timeout。
|
||
- **解决方案**：在脚本（如 `deploy.py`）中获取裸 socket 后调用 `socket.settimeout(None)`，或在 `docker-py` 调用前使用 `docker.from_env(timeout=None)`。
|
||
- **参考**：`global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56` 中的说明。
|
||
|
||
## 2. Docker Hub 代理配置失效
|
||
- **症状**：`docker pull` 失败，提示无法连接到镜像仓库。
|
||
- **根因**：Docker Desktop 代理模式未设为 *Manual*，或地址填写错误。
|
||
- **解决方案**：打开 Docker Desktop → Settings → Resources → Proxies，勾选 *Manual*，填写 `http://127.0.0.1:7897` 作为 HTTP 与 HTTPS 代理。保存后重启 Docker 并验证 `docker pull hello-world` 正常。
|
||
- **参考**：同上经验文档。
|
||
|
||
## 3. PowerShell 发送 JSON 失真
|
||
- **症状**：使用 `Invoke‑WebRequest` 发送 JSON 时，双引号被吞掉导致请求体错误。
|
||
- **根因**：PowerShell 对直接传入字符串的引号做了转义。
|
||
- **解决方案**：先将 JSON 写入临时文件，再使用 `--data-binary @file` 方式上传。
|
||
- **参考**：`global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56` 中的技巧。
|
||
|
||
## 4. FastAPI 异步函数中阻塞 I/O
|
||
- **症状**：FastAPI 路由挂起，CPU 使用率飙升，接口响应迟缓。
|
||
- **根因**：在 `async def` 中直接调用阻塞库（如 `pymysql`, `requests`, 文件读写）。
|
||
- **解决方案**：改为普通 `def`，FastAPI 会自动将其放入线程池，或使用 `run_in_executor` 包装。
|
||
- **参考**：`global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`。
|
||
|
||
## 5. Vaultwarden 凭证查找不匹配
|
||
- **症状**：在登录或 API 调用前未能自动获取密码，系统提示手动输入。
|
||
- **根因**：Vaultwarden 中存在多条匹配项或根本无匹配。
|
||
- **解决方案**：确保每条凭证的 “名称” 唯一；在脚本中使用 `search_one`（唯一匹配）而非列表返回；如果需要手动选择，请提示用户并验证选择。
|
||
- **参考**：`global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316`。
|
||
|
||
---
|
||
**参考来源**: `global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`, `global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0` |