diff --git a/docs/部署文档.md b/docs/部署文档.md
new file mode 100644
index 0000000..9240e8d
--- /dev/null
+++ b/docs/部署文档.md
@@ -0,0 +1,109 @@
+# 部署文档
+
+> 生产环境部署记录与运维手册。目标：`todolist.qingruxu.xyz`（阿里云 ECS，Ubuntu）。
+
+## 架构
+
+```
+浏览器 ── HTTPS (443) ──> Nginx 反代 ──> 127.0.0.1:6754 ──> Docker 容器 (uvicorn:8000)
+```
+
+- 容器只绑定 `127.0.0.1:6754`，**不对外暴露**，只能通过 Nginx 访问。
+- Nginx 终止 HTTPS（Let's Encrypt 证书），反代到容器。
+- 数据持久化在 Docker 命名卷 `ppm-data`。
+- 应用开启 fail-secure 认证：未设密码拒绝启动；当前用 `PPM_PASSWORD_HASH` 配置。
+
+## 服务器信息
+
+| 项 | 值 |
+|---|---|
+| SSH | `root@qingruxu.xyz`（22 端口，免密） |
+| 部署目录 | `/opt/progress-monitor/` |
+| 容器名 | `progress-monitor` |
+| 镜像 | `progress-monitor:latest` |
+| 对外域名 | `https://todolist.qingruxu.xyz` |
+| 容器端口 | `127.0.0.1:6754` |
+| Nginx 配置 | `/etc/nginx/sites-available/todolist` |
+| SSL 证书 | `/etc/letsencrypt/live/todolist.qingruxu.xyz/`（2026-11-22 到期，自动续期） |
+
+## 开机自启
+
+已配置，无需额外操作：
+
+- `systemctl is-enabled docker` = `enabled`（Docker 服务随系统自启）
+- 容器 `restart: unless-stopped`（Docker 启动后自动拉起容器）
+
+**验证命令**：
+
+```bash
+systemctl is-enabled docker          # 应输出 enabled
+docker inspect progress-monitor --format '{{.HostConfig.RestartPolicy.Name}}'   # 应输出 unless-stopped
+```
+
+## 常用运维命令
+
+```bash
+cd /opt/progress-monitor
+
+docker-compose ps              # 查看状态
+docker-compose logs -f         # 跟踪日志
+docker-compose restart         # 重启
+docker-compose down            # 停止并移除容器（数据卷保留）
+docker-compose up -d           # 启动
+```
+
+## 修改登录密码
+
+```bash
+# 1. 生成新密码哈希（任意装了 python 的机器）
+python -c "from app.auth import make_password_hash; print(make_password_hash('新密码'))"
+
+# 2. 在服务器编辑 /opt/progress-monitor/.env，替换 PPM_PASSWORD_HASH
+#    PPM_PASSWORD_HASH=pbkdf2_sha256$310000$...
+
+# 3. 重启
+cd /opt/progress-monitor && docker-compose up -d
+```
+
+## 数据备份
+
+数据在 Docker 卷 `ppm-data`，可用两种方式：
+
+**方式一：应用内导出**（推荐，登录后 ⚙ 面板 → 导出 JSON）
+得到完整备份文件，可通过「导入还原」恢复。
+
+**方式二：直接备份卷**
+
+```bash
+# 备份
+docker run --rm -v progress-monitor_ppm-data:/data -v "$(pwd)":/backup alpine tar czf /backup/ppm-data-backup.tar.gz -C /data .
+
+# 恢复
+docker run --rm -v progress-monitor_ppm-data:/data -v "$(pwd)":/backup alpine tar xzf /backup/ppm-data-backup.tar.gz -C /data
+```
+
+## 部署流程（从本机到服务器，重装时参考）
+
+```bash
+# 本机
+docker build -t progress-monitor:latest .
+docker save progress-monitor:latest -o progress-monitor.tar
+scp progress-monitor.tar docker-compose.yml .env root@qingruxu.xyz:/opt/progress-monitor/
+
+# 服务器
+cd /opt/progress-monitor
+docker load -i progress-monitor.tar
+docker-compose up -d
+```
+
+## 安全要点
+
+- **fail-secure**：`.env` 未配置 `PPM_PASSWORD_HASH` 时容器拒绝启动。
+- **HTTPS**：`PPM_COOKIE_SECURE=true`，会话 Cookie 仅在 HTTPS 下生效。
+- **登录限流**：同 IP 5 次失败锁定 60 秒。
+- **CSRF 防护**：所有写操作需 `X-CSRF-Token`。
+- 不要在生产环境设置 `PPM_PASSWORD`（明文）或 `PPM_ALLOW_NO_AUTH=1`。
+
+## 已知注意事项
+
+- 登录限流按 IP 计数；Nginx 已透传 `X-Forwarded-For`，但 uvicorn 需开启 `--proxy-headers` 才会信任该头。当前单用户场景影响小，若未来需要精确按真实 IP 限流，需在容器 CMD 加 `--proxy-headers` 并配置信任代理。