docs/v1.0/server/guides/troubleshooting-database.md

数据库连接问题排查指南

问题症状

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

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

根本原因

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

排查步骤

1. 检查 Docker 容器状态

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. 如果容器未运行，启动容器

cd server
docker-compose up -d

3. 检查 PostgreSQL 日志

docker-compose logs postgres

4. 验证数据库连接

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

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

5. 检查端口占用

# 检查 PostgreSQL 端口
lsof -i :6181

# 检查 Redis 端口
lsof -i :6183

# 检查 MinIO 端口
lsof -i :6185

常见问题和解决方案

问题 1: Docker 容器未运行

解决方案：

cd server
docker-compose up -d

问题 2: 端口被占用

解决方案：

1. 修改 docker-compose.yml 中的端口映射
2. 或者停止占用端口的进程

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

解决方案：

# 进入容器
docker-compose exec postgres psql -U postgres

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

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

问题 4: 数据库未初始化

解决方案：

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

重启后端服务

方法 1: 使用启动脚本

cd server
./start_docker.sh

方法 2: 手动启动

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

验证服务状态

1. 检查健康端点

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

期望输出：

{
  "status": "healthy",
  "timestamp": "2026-01-21T..."
}

2. 检查数据库连接

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

3. 查看服务日志

cd server
tail -f server.log

完整重置流程

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

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. 点击面包屑中的任意项，应该能正确导航

相关文档

• 部署文档
• Docker 环境配置
• 数据库迁移