自托管基础设施
本地 PostgreSQL 管理
启动、连接、检查和维护 PureChatNext 使用的本地 PostgreSQL。
PureChatNext 可以直接连接本机 PostgreSQL，不需要为了数据库功能单独部署完整 Supabase。本地实例通过 Docker Compose 与 Redis / RustFS / SearXNG 一并管理，在 Windows / macOS / Linux 上用法相同。
前置条件
- 已安装并启动 Docker Desktop（或兼容的 Docker Engine + Compose V2）
- 一次性复制 compose 环境变量：
pnpm docker:setup:dev当前约定
- 镜像：
postgres:17.10-alpine3.24（固定多架构 digest） - Compose 文件：
docker-compose/dev/docker-compose.yml - 容器名：由 Compose project 自动生成（不要依赖固定容器名）
- 连接地址：
127.0.0.1:5432 - 数据库 / 用户：默认均为
purechat；密码由pnpm docker:setup:dev随机生成，实际值以docker-compose/dev/.env为准 - 数据：Docker named volume
postgres_data
环境变量
Compose 侧（docker-compose/dev/.env）
POSTGRES_DB=purechat
POSTGRES_USER=purechat
POSTGRES_PASSWORD=<从 docker-compose/dev/.env 读取>应用侧（项目根 .env.local）
DATABASE_DRIVER=node
DATABASE_URL=postgresql://purechat:<URL 编码后的 POSTGRES_PASSWORD>@127.0.0.1:5432/purechatDATABASE_DRIVER=node 会关闭本地连接的强制 SSL。DATABASE_URL 中的用户、库名、密码必须与 compose .env 一致。密码包含 @、:、/、?、# 或 % 时必须进行 URL 编码。不要提交 .env.local 或 docker-compose/dev/.env。
启停和日常使用
与 Redis / RustFS / SearXNG 一起启停：
pnpm dev:docker # up -d --wait
pnpm db:migrate
pnpm dev:docker:down # down（保留 named volume）
pnpm dev:docker:reset # down -v 后重建，并执行 db:migrate查看状态与日志：
docker compose -f docker-compose/dev/docker-compose.yml ps postgresql
docker compose -f docker-compose/dev/docker-compose.yml logs --tail=100 postgresql
docker compose -f docker-compose/dev/docker-compose.yml logs -f postgresqldev:docker:reset 会删除全部本地 named volume（含 Postgres / Redis / RustFS），数据不可恢复。
图形工具连接
DBeaver Community、pgAdmin 4 或 Drizzle Studio 均可连接：
Host: 127.0.0.1
Port: 5432
Database: purechat
Username: purechat
Password: docker-compose/dev/.env 中的 POSTGRES_PASSWORD
SSL: disable打开项目自带的 Drizzle Studio：
pnpm db:studio备份与恢复
docker compose -f docker-compose/dev/docker-compose.yml exec -T postgresql \
pg_dump -U purechat -d purechat --format=custom --no-owner \
> purechat-backup.dump常见故障
Docker 未运行
确认 Docker Desktop（或 daemon）已启动，再执行 docker compose version。
端口被占用
# macOS / Linux
lsof -nP -iTCP:5432 -sTCP:LISTEN
# Windows PowerShell
Get-NetTCPConnection -LocalPort 5432 -ErrorAction SilentlyContinue启动失败
docker compose -f docker-compose/dev/docker-compose.yml logs --tail=100 postgresql
docker compose -f docker-compose/dev/docker-compose.yml ps