外观
常见问题与排查
本页按现象组织排查入口。命令默认在 ECS 上执行；本地开发命令会单独标注。排查时只截取必要错误行，避免复制完整生产日志。
后端不可用
| 现象 | 优先检查 | 命令 |
|---|---|---|
| App API 全部失败 | fitdoc-core 是否 active | systemctl status fitdoc-core |
/health 失败 | upstream 是否监听 8001 | ss -tlnp | grep 8001 |
| Nginx 返回 502 | 后端进程或 proxy_pass | curl -s http://127.0.0.1:8001/health |
| 启动后立即退出 | 后端日志 | journalctl -u fitdoc-core -n 100 --no-pager |
处理顺序：
bash
systemctl is-active fitdoc-core
curl -s http://127.0.0.1:8001/health
journalctl -u fitdoc-core -n 100 --no-pager
sudo systemctl restart fitdoc-core如果日志指向数据库、环境变量或 migration 错误，先修复根因再重启。
Nginx 代理异常
| 现象 | 判断 | 命令 |
|---|---|---|
| 首页打不开 | 静态根目录或 Nginx 状态异常 | systemctl status nginx |
| API 404/502 | location 或 upstream 错误 | `grep -nE 'location |
| 修改配置后失败 | 配置语法错误 | sudo nginx -t |
| HTTPS 异常 | 证书或 server block | `sudo nginx -T | grep -nE 'listen 443 |
配置变更流程：
bash
sudo nginx -t
sudo systemctl reload nginx
curl -s http://127.0.0.1/health当前 /docs 被后端文档代理规则覆盖。VitePress 文档站发布到 /doc-center/，避免覆盖 FastAPI Swagger。
数据库连接失败
| 现象 | 判断 | 检查方式 |
|---|---|---|
| 后端启动时报数据库连接错误 | DATABASE_URL、RDS 白名单或网络异常 | 检查 .env key 是否存在，不输出真实值。 |
| Alembic 失败 | migration 链或连接权限异常 | alembic current、alembic upgrade head。 |
| API 超时 | RDS 连接池或慢查询 | 先看后端日志中的错误类型，再决定是否查数据库元数据。 |
本地开发如果需要访问 RDS，应使用受控 SSH 隧道或开发库，不把生产连接串写入命令历史或文档。
RAG 或 LLM 响应失败
| 现象 | 优先检查 | 来源 |
|---|---|---|
| AI 回复降级或失败 | LLM_PROVIDER、LLM_MODEL 与对应凭据是否存在 | 后端 .env key 列表 |
| RAG 检索为空 | RAG_PIPELINE_VERSION、RAG_HYBRID_SCHEMA_TAG、knowledge_chunks | AI/RAG 与数据库 reference |
| rerank 超时 | RAG_ENABLE_RERANK、timeout、circuit breaker | app/core/rag/reranker.py |
| embedding 失败 | DASHSCOPE_API_KEY 与外部服务可用性 | RAG 检索日志 |
可先运行后端 RAG 护栏脚本：
bash
cd /opt/fitdoc/backend
source venv/bin/activate
python scripts/rag/run_rag_production_guardrails.py生产排查只记录错误类型、模块名和时间点，不复制模型请求正文、患者输入全文或外部服务凭据。
文档站路径混淆
| 现象 | 原因 | 处理 |
|---|---|---|
访问生产 /docs 看到 FastAPI Swagger | 当前 Nginx 将 /docs 代理到 fitdoc-core。 | 这是当前生产事实。 |
访问生产 /docs 看到 FastAPI Swagger | 当前 Nginx 将 /docs 代理到 fitdoc-core。 | 这是当前生产事实，文档中心入口为 /doc-center/。 |
本地 VitePress /doc-center/ 正常，生产 /doc-center/ 不显示文档站 | 文档站构建产物尚未复制到 /opt/fitdoc/frontend/doc-center/。 | 重新发布 docs_site/.vitepress/dist/。 |
| 文档站静态资源 404 | base: '/doc-center/' 与部署目录不一致，或静态产物未完整同步。 | 核对 docs_site/.vitepress/config.ts 和 /opt/fitdoc/frontend/doc-center/。 |
本地构建验证：
powershell
cd D:\Fitdoc_app\docs_site
npm run docs:build
npm run docs:previewFlutter 请求失败
| 现象 | 判断 | 检查 |
|---|---|---|
| 所有接口 404 | API_BASE_URL 未包含 /api | 查看构建命令中的 --dart-define=API_BASE_URL。 |
| Web 调试 CORS 报错 | 后端 CORS origin 未放行 | 检查 CORS_ALLOW_ORIGINS 或 CORS_ALLOW_ORIGIN_REGEX。 |
| 真机无法访问本机后端 | localhost 指向手机自身 | 使用局域网 IP 或可访问的测试服务地址。 |
| 视频无法播放 | VIDEO_BASE_URL 或 Nginx 静态路径错误 | 访问具体 /static/videos/ 资源。 |
APK 构建或安装失败
| 现象 | 判断 | 命令 |
|---|---|---|
| 依赖失败 | Flutter/Dart 版本或网络问题 | flutter pub get -v |
| 编译失败 | Android Gradle、NDK 或代码错误 | flutter build apk --release -v |
| 安装失败 | 设备已有冲突包或签名不一致 | adb install -r <apk> |
| 发布签名不符合要求 | 当前 release 使用 debug signing | 查看 android/app/build.gradle.kts |
当前 release signing 不是正式商店签名配置。对外发布前需要独立补齐 keystore 和安全注入。
快速命令索引
bash
systemctl is-active fitdoc-core nginx gitea
systemctl is-enabled fitdoc-core nginx gitea
ss -tlnp | grep -E '(:80|:443|:8001|:3000)'
curl -s http://127.0.0.1:8001/health
curl -s http://127.0.0.1/health
sudo nginx -t
journalctl -u fitdoc-core -n 100 --no-pager来源锚点
docs/新服务器运维手册.md- 生产 ECS 只读服务状态与 Nginx 配置核验
apps/backend_service/scripts/README.mdapps/backend_service/app/core/config.pyapps/flutter_app/lib/config/environment_config.dartapps/flutter_app/android/app/build.gradle.kts