# 错误：归档命令失败，退出码为 1

- **ID:** `database/postgresql-wal-archive-timeout`
- **领域:** database
- **类别:** system_error
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

PostgreSQL 的 archive_command（例如 cp 或 rsync）因磁盘空间不足、权限问题或网络不可达而失败，导致 WAL 归档停滞，可能引发复制延迟或事务丢失。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| PostgreSQL 15.6 | active | — | — |
| PostgreSQL 14.11 | active | — | — |
| PostgreSQL 16.2 | active | — | — |

## 解决方案

1. ```
   Check the archive destination for disk space (df -h /archive/path) and permissions (ls -ld /archive/path). If full, free space or move to a different location; then update archive_command in postgresql.conf and reload: SELECT pg_reload_conf();
   ```
2. ```
   Test the archive command manually: su - postgres -c 'archive_command_test' (e.g., cp /path/to/test.wal /archive/). If it fails, fix the command (e.g., add -p to mkdir) or switch to a simpler method like pg_receivewal.
   ```
3. ```
   If the archive destination is temporarily unavailable, set archive_mode = off in postgresql.conf and restart, then re-enable it after fixing the destination: ALTER SYSTEM SET archive_mode = off; SELECT pg_reload_conf(); -- then fix destination, then set archive_mode = on.
   ```

## 无效尝试

- **Increasing archive_timeout to reduce archiving frequency** — This only delays the failure; the archive command will still fail if the underlying issue (e.g., disk space) is not resolved. (90% 失败率)
- **Setting archive_mode = off to stop archiving entirely** — This disables WAL archiving, which may be required for PITR or replication; it also leaves the system without a backup strategy, risking data loss. (85% 失败率)
- **Restarting PostgreSQL without fixing the archive destination** — Restarting does not resolve the root cause; the archive command will fail again immediately after the restart. (100% 失败率)