---
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: git-restore
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: null
created_at: '2026-09-02T18:36:51.454085+00:00'
updated_at: '2026-09-23T15:05:18.549631+00:00'
tags:
- troubleshooting
- development
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

# 常见问题及排障指南 (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`