# 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:
   ```bash
   # 使用Homebrew
   brew install direnv openssl
   ```

   Linux:
   ```bash
   apt-get update
   apt-get install direnv openssl
   ```

2. **执行交互式初始化**

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

   初始化过程会引导您设置：
   - 数据库密码（PostgreSQL root密码）
   - 加密主密钥（用于加密/解密密码文件）
   - 服务端口（默认为25001）
   - 容器名称（默认为guarddoc-server-postgres）

3. **设置文件权限**

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

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

### 服务管理命令

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

```bash
cd /path/to/server/database

# 启动服务
./service start

# 停止服务
./service stop

# 检查服务状态
./service status

# 重启服务
./service restart

# 查看帮助信息
./service help
```

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

### 连接数据库

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

```bash
# 使用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. 停止服务：
   ```bash
   ./service stop
   ```

2. 删除现有的配置文件：
   ```bash
   rm -f .envrc postgres_password.enc
   ```

3. 重新运行初始化脚本：
   ```bash
   ./init
   ```

4. 重新启动服务：
   ```bash
   ./service start
   ```

### 添加自定义PostgreSQL配置

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

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

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

## 备份与恢复

### 执行数据库备份

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

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

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

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

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

### 数据库恢复

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

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

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

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

### 定时备份

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

```bash
# 编辑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 [<database>] [<days>]|
|restore|数据库恢复|./restore [<database>]|
|clear|清空所有数据（保留备份目录）|./clear|