Skip to content

Commit 1da0157

Browse files
whispinwhispin
committed
Add initial documentation for PostgreSQL backup system
1 parent 693c28e commit 1da0157

7 files changed

Lines changed: 1421 additions & 0 deletions

File tree

‎MANUAL_BACKUP_GUIDE.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# 手动备份操作指南
2+
3+
## 概述
4+
5+
现在你可以在容器内手动触发PostgreSQL备份操作。我们提供了一个专门的脚本 `manual-backup.sh` 来执行各种类型的备份。
6+
7+
## 使用方法
8+
9+
### 基本语法
10+
11+
```bash
12+
docker exec <container_name> /backup/scripts/manual-backup.sh [OPTIONS]
13+
```
14+
15+
### 可用选项
16+
17+
| 选项 | 长选项 | 描述 |
18+
|------|--------|------|
19+
| `-h` | `--help` | 显示帮助信息 |
20+
| `-f` | `--full` | 执行完整备份（默认） |
21+
| `-i` | `--incremental` | 执行增量备份 |
22+
| `-d` | `--diff` | 执行差异备份 |
23+
| `-c` | `--check` | 检查备份状态和配置 |
24+
| `-l` | `--list` | 列出可用的备份 |
25+
| `-v` | `--verbose` | 启用详细输出 |
26+
27+
## 实际使用示例
28+
29+
假设你的容器名称是 `postgres-backup-container`：
30+
31+
### 1. 执行完整备份
32+
33+
```bash
34+
# 方法1：使用默认设置
35+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh
36+
37+
# 方法2：明确指定完整备份
38+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh --full
39+
40+
# 方法3：带详细输出的完整备份
41+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh --full --verbose
42+
```
43+
44+
### 2. 执行增量备份
45+
46+
```bash
47+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh --incremental
48+
```
49+
50+
### 3. 执行差异备份
51+
52+
```bash
53+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh --diff
54+
```
55+
56+
### 4. 检查备份配置
57+
58+
```bash
59+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh --check
60+
```
61+
62+
### 5. 列出可用备份
63+
64+
```bash
65+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh --list
66+
```
67+
68+
### 6. 查看帮助信息
69+
70+
```bash
71+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh --help
72+
```
73+
74+
## 备份类型说明
75+
76+
### 完整备份 (Full Backup)
77+
- **用途**: 创建数据库的完整副本
78+
- **特点**: 包含所有数据，可以独立恢复
79+
- **建议**: 定期执行，作为其他备份类型的基础
80+
81+
### 增量备份 (Incremental Backup)
82+
- **用途**: 只备份自上次备份以来的更改
83+
- **特点**: 备份速度快，占用空间小
84+
- **要求**: 需要有完整备份作为基础
85+
- **智能检查**: 如果没有全量备份，会自动先执行一次全量备份
86+
87+
### 差异备份 (Differential Backup)
88+
- **用途**: 备份自上次完整备份以来的所有更改
89+
- **特点**: 比增量备份大，但恢复更简单
90+
- **要求**: 需要有完整备份作为基础
91+
- **智能检查**: 如果没有全量备份，会自动先执行一次全量备份
92+
93+
## 监控和日志
94+
95+
### 查看备份日志
96+
97+
```bash
98+
# 查看实时日志
99+
docker exec postgres-backup-container tail -f /backup/logs/backup.log
100+
101+
# 查看最近的日志
102+
docker exec postgres-backup-container tail -50 /backup/logs/backup.log
103+
104+
# 搜索特定内容
105+
docker exec postgres-backup-container grep "ERROR\|WARN" /backup/logs/backup.log
106+
```
107+
108+
### 检查容器状态
109+
110+
```bash
111+
# 检查容器是否运行
112+
docker ps | grep postgres-backup
113+
114+
# 查看容器日志
115+
docker logs postgres-backup-container
116+
117+
# 检查健康状态
118+
docker exec postgres-backup-container /backup/scripts/healthcheck.sh
119+
```
120+
121+
## 故障排除
122+
123+
### 常见问题
124+
125+
1. **权限错误**
126+
```bash
127+
# 检查文件权限
128+
docker exec postgres-backup-container ls -la /backup/scripts/
129+
```
130+
131+
2. **PostgreSQL连接失败**
132+
```bash
133+
# 检查PostgreSQL状态
134+
docker exec postgres-backup-container pg_isready -U $POSTGRES_USER -d $POSTGRES_DB
135+
```
136+
137+
3. **rclone配置问题**
138+
```bash
139+
# 检查rclone配置
140+
docker exec postgres-backup-container rclone config show
141+
```
142+
143+
### 调试模式
144+
145+
启用详细输出来调试问题：
146+
147+
```bash
148+
docker exec postgres-backup-container /backup/scripts/manual-backup.sh --full --verbose
149+
```
150+
151+
## 最佳实践
152+
153+
1. **定期完整备份**: 每周至少执行一次完整备份
154+
2. **增量备份**: 在完整备份之间执行增量备份
155+
3. **验证备份**: 定期检查备份的完整性
156+
4. **监控日志**: 定期查看备份日志确保没有错误
157+
5. **测试恢复**: 定期测试备份恢复过程
158+
159+
## 自动化示例
160+
161+
你也可以创建脚本来自动化备份操作：
162+
163+
```bash
164+
#!/bin/bash
165+
# backup-automation.sh
166+
167+
CONTAINER_NAME="postgres-backup-container"
168+
169+
# 每日增量备份
170+
docker exec $CONTAINER_NAME /backup/scripts/manual-backup.sh --incremental
171+
172+
# 检查备份状态
173+
if [ $? -eq 0 ]; then
174+
echo "备份成功完成"
175+
else
176+
echo "备份失败，请检查日志"
177+
docker exec $CONTAINER_NAME tail -20 /backup/logs/backup.log
178+
fi
179+
```
180+
181+
## 注意事项
182+
183+
1. 确保容器有足够的磁盘空间
184+
2. 备份过程中避免对数据库进行大量写操作
185+
3. 定期清理旧的备份文件以节省空间
186+
4. 确保rclone配置正确以便远程存储

‎QUICK_START_EN.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Quick Start Guide
2+
3+
## 🚀 Getting Started in 5 Minutes
4+
5+
### Prerequisites
6+
7+
- Docker installed and running
8+
- PostgreSQL database to backup
9+
- rclone configuration for remote storage (optional)
10+
11+
### Step 1: Prepare rclone Configuration
12+
13+
Create a base64 encoded rclone configuration:
14+
15+
```bash
16+
# Create rclone config file
17+
cat > rclone.conf << EOF
18+
[s3-remote]
19+
type = s3
20+
provider = AWS
21+
access_key_id = your_access_key
22+
secret_access_key = your_secret_key
23+
region = us-east-1
24+
EOF
25+
26+
# Encode to base64
27+
RCLONE_CONF_BASE64=$(cat rclone.conf | base64 -w 0)
28+
echo $RCLONE_CONF_BASE64
29+
```
30+
31+
### Step 2: Run Backup Container
32+
33+
```bash
34+
docker run -d \
35+
--name postgres-backup \
36+
-e POSTGRES_USER=myuser \
37+
-e POSTGRES_PASSWORD=mypassword \
38+
-e POSTGRES_DB=mydatabase \
39+
-e RCLONE_CONF_BASE64="$RCLONE_CONF_BASE64" \
40+
-e PGBACKREST_STANZA=main \
41+
-e WAL_GROWTH_THRESHOLD="100MB" \
42+
-v /var/lib/postgresql/data:/var/lib/postgresql/data:ro \
43+
-v ./backup-logs:/backup/logs \
44+
ghcr.io/whispin/postgres_nrt_backup:latest
45+
```
46+
47+
### Step 3: Verify Backup System
48+
49+
```bash
50+
# Check container status
51+
docker ps | grep postgres-backup
52+
53+
# Check logs
54+
docker logs postgres-backup
55+
56+
# Verify backup configuration
57+
docker exec postgres-backup /backup/scripts/manual-backup.sh --check
58+
```
59+
60+
### Step 4: Perform Manual Backup
61+
62+
```bash
63+
# Full backup
64+
docker exec postgres-backup /backup/scripts/manual-backup.sh --full
65+
66+
# Check backup status
67+
docker exec postgres-backup /backup/scripts/manual-backup.sh --list
68+
```
69+
70+
### Step 5: Monitor WAL Growth
71+
72+
```bash
73+
# Check WAL monitor status
74+
docker exec postgres-backup /backup/scripts/wal-control.sh status
75+
76+
# View WAL monitor logs
77+
docker exec postgres-backup /backup/scripts/wal-control.sh logs -n 20
78+
```
79+
80+
## 🔄 Recovery Example
81+
82+
### Recover to Latest Backup
83+
84+
```bash
85+
docker run -d \
86+
--name postgres-recovery \
87+
-e POSTGRES_USER=myuser \
88+
-e POSTGRES_PASSWORD=mypassword \
89+
-e POSTGRES_DB=mydatabase \
90+
-e RCLONE_CONF_BASE64="$RCLONE_CONF_BASE64" \
91+
-e RECOVERY_MODE="true" \
92+
-v ./recovery-data:/var/lib/postgresql/data \
93+
ghcr.io/whispin/postgres_nrt_backup:latest
94+
```
95+
96+
### Point-in-Time Recovery
97+
98+
```bash
99+
docker run -d \
100+
--name postgres-recovery \
101+
-e POSTGRES_USER=myuser \
102+
-e POSTGRES_PASSWORD=mypassword \
103+
-e POSTGRES_DB=mydatabase \
104+
-e RCLONE_CONF_BASE64="$RCLONE_CONF_BASE64" \
105+
-e RECOVERY_MODE="true" \
106+
-e RECOVERY_TARGET_TIME="2025-07-10 14:30:00" \
107+
-v ./recovery-data:/var/lib/postgresql/data \
108+
ghcr.io/whispin/postgres_nrt_backup:latest
109+
```
110+
111+
## 📊 Monitoring
112+
113+
### Check Backup Status
114+
115+
```bash
116+
# View backup logs
117+
docker exec postgres-backup tail -f /backup/logs/backup.log
118+
119+
# Check WAL monitor
120+
docker exec postgres-backup /backup/scripts/wal-control.sh status
121+
122+
# List all backups
123+
docker exec postgres-backup /backup/scripts/manual-backup.sh --list
124+
```
125+
126+
### Health Check
127+
128+
```bash
129+
# Run health check
130+
docker exec postgres-backup /backup/scripts/healthcheck.sh
131+
132+
# Check container health
133+
docker inspect postgres-backup | grep Health -A 10
134+
```
135+
136+
## 🛠️ Troubleshooting
137+
138+
### Common Issues
139+
140+
1. **Container fails to start**
141+
```bash
142+
# Check logs
143+
docker logs postgres-backup
144+
145+
# Check environment variables
146+
docker exec postgres-backup env | grep POSTGRES
147+
```
148+
149+
2. **Backup fails**
150+
```bash
151+
# Check backup logs
152+
docker exec postgres-backup cat /backup/logs/backup.log
153+
154+
# Test PostgreSQL connection
155+
docker exec postgres-backup pg_isready -U $POSTGRES_USER -d $POSTGRES_DB
156+
```
157+
158+
3. **Remote storage issues**
159+
```bash
160+
# Test rclone configuration
161+
docker exec postgres-backup rclone config show
162+
163+
# Test remote connection
164+
docker exec postgres-backup /backup/scripts/recovery-control.sh test-connection
165+
```
166+
167+
### Debug Mode
168+
169+
```bash
170+
# Run with debug logging
171+
docker run -d \
172+
--name postgres-backup \
173+
-e DEBUG="true" \
174+
-e POSTGRES_USER=myuser \
175+
# ... other environment variables
176+
ghcr.io/whispin/postgres_nrt_backup:latest
177+
```
178+
179+
## 📚 Next Steps
180+
181+
- Read the [Manual Backup Guide](MANUAL_BACKUP_GUIDE.md)
182+
- Learn about [WAL Monitoring](WAL_MONITOR_GUIDE.md)
183+
- Explore [Recovery Options](RECOVERY_GUIDE.md)
184+
- Understand [Smart Backup Logic](SMART_BACKUP_LOGIC.md)
185+
186+
## 💡 Tips
187+
188+
1. **Set appropriate WAL threshold**: Start with 100MB and adjust based on your database activity
189+
2. **Monitor backup logs**: Regularly check logs for any issues
190+
3. **Test recovery**: Periodically test your backup recovery process
191+
4. **Use health checks**: Enable Docker health checks for monitoring
192+
5. **Backup retention**: Adjust retention days based on your requirements
193+
194+
That's it! Your PostgreSQL backup system is now running with automatic WAL monitoring and remote storage support.

0 commit comments

Comments
 (0)