# 数据库连接问题排查指南

## 问题症状

```
ERROR: role "postgres" does not exist
ERROR: Application startup failed. Exiting.
```

前端所有 API 请求失败，显示 CORS 错误和 500 错误。

## 根本原因

后端服务器无法启动，因为无法连接到 PostgreSQL 数据库。

## 排查步骤

### 1. 检查 Docker 容器状态

```bash
cd server
docker-compose ps
```

**期望输出**：
```
NAME                IMAGE               STATUS
jointo-postgres   postgres:17         Up
jointo-redis      redis:7-alpine      Up
jointo-minio      minio/minio         Up
```

### 2. 如果容器未运行，启动容器

```bash
cd server
docker-compose up -d
```

### 3. 检查 PostgreSQL 日志

```bash
docker-compose logs postgres
```

### 4. 验证数据库连接

```bash
# 进入 PostgreSQL 容器
docker-compose exec postgres psql -U postgres -d jointo

# 在 psql 中执行
\du  # 查看用户列表
\l   # 查看数据库列表
\q   # 退出
```

### 5. 检查端口占用

```bash
# 检查 PostgreSQL 端口
lsof -i :6181

# 检查 Redis 端口
lsof -i :6183

# 检查 MinIO 端口
lsof -i :6185
```

## 常见问题和解决方案

### 问题 1: Docker 容器未运行

**解决方案**：
```bash
cd server
docker-compose up -d
```

### 问题 2: 端口被占用

**解决方案**：
1. 修改 `docker-compose.yml` 中的端口映射
2. 或者停止占用端口的进程

### 问题 3: 数据库用户不存在

**解决方案**：
```bash
# 进入容器
docker-compose exec postgres psql -U postgres

# 创建用户（如果需要）
CREATE USER postgres WITH PASSWORD 'postgres';
ALTER USER postgres WITH SUPERUSER;

# 创建数据库（如果需要）
CREATE DATABASE jointo OWNER postgres;
```

### 问题 4: 数据库未初始化

**解决方案**：
```bash
# 运行数据库迁移
cd server
python run_migration.py
```

## 重启后端服务

### 方法 1: 使用启动脚本

```bash
cd server
./start_docker.sh
```

### 方法 2: 手动启动

```bash
cd server
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 6170 --reload
```

## 验证服务状态

### 1. 检查健康端点

```bash
curl http://localhost:6170/api/v1/health
```

**期望输出**：
```json
{
  "status": "healthy",
  "timestamp": "2026-01-21T..."
}
```

### 2. 检查数据库连接

```bash
curl http://localhost:6170/api/v1/health/db
```

### 3. 查看服务日志

```bash
cd server
tail -f server.log
```

## 完整重置流程

如果以上方法都不行，可以完全重置：

```bash
cd server

# 1. 停止所有容器
docker-compose down -v

# 2. 清理数据卷（警告：会删除所有数据）
docker volume prune -f

# 3. 重新启动容器
docker-compose up -d

# 4. 等待容器启动（约 10 秒）
sleep 10

# 5. 运行数据库迁移
python run_migration.py

# 6. 启动后端服务
./start_docker.sh
```

## 面包屑功能测试

数据库和后端服务正常运行后，面包屑功能应该可以正常工作：

1. 打开前端：http://localhost:6160/projects
2. 点击任意文件夹
3. 查看页面顶部的面包屑导航
4. 点击面包屑中的任意项，应该能正确导航

## 相关文档

- [部署文档](../DEPLOYMENT.md)
- [Docker 环境配置](../../.archive/server/docker-environment.md)
- [数据库迁移](../MIGRATION_README.md)