PostgreSQL数据库服务

本目录提供了基于Docker的PostgreSQL数据库服务，使用direnv和OpenSSL实现安全的密码管理，避免在配置文件中硬编码敏感信息。系统采用交互式初始化脚本和统一的服务管理脚本，简化了部署和维护流程。

目录结构及文件说明

├── .envrc                # 环境变量配置文件，使用direnv管理
├── .gitignore            # Git忽略文件配置
├── README.md             # 本文档
├── clear                 # 清理数据库数据的脚本
├── conf/                 # PostgreSQL配置文件目录
├── data/                 # PostgreSQL数据存储目录
├── docker-compose.yml    # Docker Compose配置文件
├── fulldump              # 数据库完全备份脚本（支持多数据库备份）
├── init                  # 交互式初始化配置脚本
├── postgres_password.enc # 加密的数据库密码文件
├── restore               # 数据库恢复脚本（支持智能备份选择）
└── service               # 统一的服务管理脚本（替代原start/stop脚本）

环境要求

开发环境

• macOS
• Docker 和 Docker Compose
• direnv (brew install direnv)
• OpenSSL

生产环境

• 支持主流Linux发行版，包括但不限于银河麒麟服务器系统v10、Debian 12等
• Docker 和 Docker Compose（自动处理架构兼容性）
• direnv (apt-get install direnv 或发行版对应包管理器)
• OpenSSL

注意：Docker会自动处理ARM和x64架构的兼容性，本方案不区分硬件架构

使用方法

首次使用配置

1. 安装依赖

   macOS:

   # 使用Homebrew
   brew install direnv openssl
   

   Linux:

   apt-get update
   apt-get install direnv openssl
   

2. 执行交互式初始化

   cd /path/to/server/database
   chmod +x init service
   ./init
   

   初始化过程会引导您设置：

   • 数据库密码（PostgreSQL root密码）
   • 加密主密钥（用于加密/解密密码文件）
   • 服务端口（默认为25001）
   • 容器名称（默认为guarddoc-server-postgres）

3. 设置文件权限

   chmod 600 .envrc postgres_password.enc
   chmod +x clear fulldump
   

注意：初始化脚本会自动执行direnv allow，无需手动操作。如果初始化过程中密码验证失败，脚本会立即停止执行。

服务管理命令

使用统一的service脚本来管理PostgreSQL服务：

cd /path/to/server/database

# 启动服务
./service start

# 停止服务
./service stop

# 检查服务状态
./service status

# 重启服务
./service restart

# 查看帮助信息
./service help

注意：所有命令执行前都需要输入加密主密钥进行验证。如果密码验证失败，命令会立即停止执行。

连接数据库

数据库服务使用在初始化过程中指定的端口（默认为5432）：

# 使用psql客户端连接
psql -h localhost -p 5432 -U postgres
# 输入初始化过程中设置的数据库密码

安全注意事项

1. 密码管理

   • 数据库密码使用AES-256-CBC加密存储，采用PBKDF2密钥派生函数增强安全性
   • 主密钥仅保存在用户记忆中，不存储在任何文件中
   • 环境变量在离开工作目录时自动清除（direnv特性）
   • 所有服务管理命令都需要密码验证才能执行

2. 文件权限

   • 敏感文件(.envrc, postgres_password.enc)设置严格的600权限
   • 容器内数据目录使用PostgreSQL用户权限(700)

3. 注意事项

   • 请妥善保管主密钥，丢失后无法恢复数据库密码
   • 定期备份数据库，避免数据丢失
   • 不要将.envrc和postgres_password.enc提交到版本控制系统（已在.gitignore中配置）

自定义配置

修改现有配置

如果需要修改已初始化的配置：

1. 停止服务：

   ./service stop
   

2. 删除现有的配置文件：

   rm -f .envrc postgres_password.enc
   

3. 重新运行初始化脚本：

   ./init
   

4. 重新启动服务：

   ./service start
   

添加自定义PostgreSQL配置

在conf/目录下添加配置文件，服务启动时会自动复制到容器内并应用：

# 示例：修改最大连接数
cat > conf/postgresql.conf << EOF
max_connections = 200
EOF

# 重启服务以应用配置
./service restart

备份与恢复

执行数据库备份

使用fulldump脚本进行数据库备份：

# 备份所有用户数据库（排除系统数据库），默认清除15天前的备份
./fulldump

# 备份指定数据库，默认清除15天前的备份
./fulldump <database_name>

# 备份指定数据库，并清除指定天数前的备份
./fulldump <database_name> <days>

备份文件将保存在data/backup/目录中，命名格式为<database_name>_full_<timestamp>。

数据库恢复

使用restore脚本从备份恢复数据库：

# 恢复最新备份到原始数据库（根据备份文件名自动确定目标数据库）
./restore

# 恢复指定数据库的最新备份（优先查找与数据库名匹配的备份）
./restore <database_name>

脚本会选择与目标数据库匹配的最新备份文件（如果指定了数据库名），并在恢复前提供确认提示，避免误操作。

定时备份

将fulldump脚本加入到系统crontab定时任务中实现定时备份：

# 编辑crontab
crontab -e

# 添加以下行（每天1点备份所有用户数据库并清除15天前的备份）
0 1 * * * bash /path/to/server/database/fulldump 15

# 或者只备份特定数据库
0 1 * * * bash /path/to/server/database/fulldump <database_name> 15

故障排除

常见问题

1. 密码验证失败

   • 错误提示："错误: POSTGRES_PASSWORD环境变量未设置"
   • 解决方案：确保输入正确的加密主密钥

2. direnv未安装

   • 错误提示："警告: direnv未安装"
   • 解决方案：按照环境要求部分安装direnv
   • macOS: brew install direnv
   • Linux: apt-get install direnv

3. 容器名称冲突

   • 错误提示："Error response from daemon: Conflict. The container name ... is already in use"
   • 解决方案：使用不同的容器名称重新初始化

4. 端口冲突

   • 错误提示："Error starting userland proxy: listen tcp4 0.0.0.0:25001: bind: address already in use"
   • 解决方案：使用不同的端口重新初始化

脚本工具详情

脚本	作用	用法
init	交互式初始化数据库配置	./init
service	统一服务管理（支持start/stop/status/restart）	./service [command]
fulldump	数据库全量备份	./fulldump [] []
restore	数据库恢复	./restore []
clear	清空所有数据（保留备份目录）	./clear