# 故障排除

FluxiQ PIX 常见问题及其解决方案。

## 前提条件

- 访问后端日志（`kubectl logs` 或 Docker 日志）
- 熟悉 Elixir/OTP 错误消息
- 访问 PostgreSQL、Redis 和 NATS 进行诊断

## 快速诊断

```bash
# 检查所有 Pod
kubectl get pods -n pix

# 后端日志（最后 100 行）
kubectl logs -n pix deployment/pix-backend --tail=100

# 健康检查
curl -s http://localhost:4003/health | jq .

# 数据库连接
kubectl exec -n pix deployment/pix-backend -- bin/monetarie_pix eval "Shared.Repo.query!('SELECT 1')"
```

## 常见问题

### 后端启动失败

**症状**：Pod 处于 CrashLoopBackOff 状态

**原因和解决方案**：

| 原因 | 日志模式 | 解决方案 |
|------|----------|----------|
| 缺少 SECRET_KEY_BASE | `KeyError: SECRET_KEY_BASE` | 在 K8s Secret 中设置密钥 |
| 数据库不可达 | `Postgrex.Error: tcp connect` | 检查 DB_HOST 和网络 |
| 无效 DATABASE_URL | `URI.parse error` | URL 编码特殊字符 |
| 端口冲突 | `eaddrinuse` | 检查 4001-4003 端口无其他进程 |

### 迁移失败

**症状**：`Shared.Release.migrate()` 报错

```bash
# 检查迁移状态
kubectl exec -n pix deployment/pix-backend -- \
  bin/monetarie_pix eval "Ecto.Migrator.migrations(Shared.Repo, \"apps/shared/priv/repo/migrations\")"
```

**常见原因**：
- 扩展未安装：执行 `CREATE EXTENSION IF NOT EXISTS "uuid-ossp"` 和 `pg_trgm`
- 表已存在：迁移处理 DROP + CREATE 以兼容遗留表
- 权限不足：数据库用户需要 CREATE/ALTER/DROP 权限

### NATS Worker 未启动

**症状**：无 Worker 日志消息

**检查清单**：
1. 验证环境中 `NATS_ENABLED=true`
2. 检查 NATS 连接：`nats server check connection`
3. 验证 NATS 服务器已启用 JetStream
4. 检查日志中是否有 `"NATS not enabled, skipping worker init"`

### CoreEventProcessor 超时

**症状**：日志中出现 `Finch.Error: timeout`

**原因**：
- DICT 服务未响应（检查 `DICT_SERVICE_URL`）
- MONETARIE_CORE 流未创建（Core 团队依赖）
- Pod 间网络问题

**解决方案**：
```bash
# 验证 DICT 服务
curl http://localhost:4001/api/health

# 检查 MONETARIE_CORE 流是否存在
nats stream info MONETARIE_CORE
```

### 登录失败

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| 401 Unauthorized | 凭据错误 | 验证用户名/密码 |
| 429 Too Many Requests | 速率限制 | 等待 15 分钟或检查 Redis |
| 账户已锁定 | 10 次失败尝试 | 管理员需手动解锁用户 |
| 需要 MFA | MFA 已启用 | 完成 MFA 验证步骤 |

### 断路器打开

**症状**：Settlement 服务返回 HTTP 503

```bash
# 通过日志检查断路器状态
kubectl logs -n pix deployment/pix-backend | grep "circuit_breaker"
```

**解决方案**：断路器 30 秒后自动恢复（半开状态）。如果持续存在，检查失败的下游服务。

### GIN 三元组索引失败

**症状**：CHAR 列上 `gin_trgm_ops` 迁移错误

**解决方案**：在索引表达式中将 CHAR 转换为 text：
```sql
CREATE INDEX idx_e2e_trgm ON monetarie_spi.messages USING gin ((end_to_end_id::text) gin_trgm_ops);
```

### WebSocket 连接失败

**症状**：监控仪表板显示"已断开"

**检查清单**：
1. JWT Token 有效且未过期
2. nginx/Traefik 已配置 WebSocket 升级
3. 后端 Settlement Service 运行在端口 4003
4. 检查浏览器控制台 WebSocket 错误

### Redis 连接问题

**症状**：速率限制或幂等性功能异常

```bash
# 测试 Redis 连接
redis-cli -h $REDIS_HOST -p $REDIS_PORT ping

# 检查 Redis 内存
redis-cli -h $REDIS_HOST INFO memory
```

## 日志关联

所有请求携带 `x-trace-id` 头进行分布式追踪：

```bash
# 查找特定追踪的所有日志
kubectl logs -n pix deployment/pix-backend | grep "trace_id=abc123"
```

NATS 消息也在消息头中携带 `trace_id` 进行端到端关联。

## 常用 Elixir 诊断

```bash
# 远程控制台（仅限开发环境）
kubectl exec -it -n pix deployment/pix-backend -- bin/monetarie_pix remote

# 检查运行进程
Process.list() |> length()

# 检查 ETS 表
:ets.all() |> length()

# 检查内存
:erlang.memory()
```

## 预期结果

使用本故障排除指南后：

- 快速识别和解决常见问题
- 日志关联实现端到端请求追踪
- 了解断路器、速率限制器和 NATS Worker 行为
- 掌握所有基础设施组件的诊断命令