# NAS 一键部署

## 前置条件

1. **本机安装 paramiko**（仅第一次用）：

```bash
C:/Users/PF/.workbuddy/binaries/python/envs/default/Scripts/pip.exe install paramiko
```

2. **配置 SSH 密码**（环境变量，避免每次交互输入）：

```bash
set SSH_PASS=peng4077
```

或直接交互式输入。

## 快速上手

```bash
# 完整流程：打包 → 上传 → 同步图标 → 构建 → 重启 → 体检
SSH_PASS=peng4077 python deploy/nas/deploy.py

# 只改了模板/静态文件，不需要重装依赖和重新编译镜像
SSH_PASS=peng4077 python deploy/nas/deploy.py --no-build

# 只同步 favicon 种子（NAS 无外网，靠种子才有真实图标）
SSH_PASS=peng4077 python deploy/nas/deploy.py --icons-only

# 只看远端状态，不改任何东西
SSH_PASS=peng4077 python deploy/nas/deploy.py --check

# 本地打包预览（不打包进 .env/data/venv 等禁忌项）
SSH_PASS=peng4077 python deploy/nas/deploy.py --pack-only
```

## 环境变更

可覆盖的默认值：

| 变量 | 默认 | 说明 |
|------|------|------|
| `NAS_HOST` | `192.168.1.102` | NAS IP |
| `NAS_USER` | `bwadmin` | SSH 用户名 |
| `NAS_PORT` | `22` | SSH 端口 |
| `NAS_DIR` | `/home/bwadmin/pear-admin-flask` | NAS 上的项目目录 |
| `SSH_PASS` | 交互式输入 | 密码（所有 sudo 命令共用） |

## 脚本做了什么

1. **打包** — 排除 `.git`、`venv`、`data`、`.env`、`*.db`、`__pycache__`、`flask_session`、`logs`、`output` 等一次性/运行时产物；只打进源码 + 配置 + 部署文件。
2. **上传** — 通过 SFTP 把 tar.gz 传到 NAS `/tmp`。
3. **解包** — `sudo tar xzf` 覆盖项目目录，`chown bwadmin:bwadmin` 改属主。**刻意跳过** `deploy/nas/data`（数据卷属主 uid 1001 = 容器内 appuser，改错了容器会失去写权限）。
4. **同步图标** — 把本地 `data/icon/` 下的真实 favicon 打进 `deploy/nas/data/icon/`（NAS 容器无外网，抓不到 favicon，必须靠种子才有真实图标）。
5. **构建镜像** — `docker compose build`，**不加 `--pull`**（NAS 的 registry 镜像常返回 401，本地 `python:3.11-slim` 缓存已够用）。
6. **启动容器** — `docker compose up -d`（容器会被重建，但 `deploy/nas/data` 数据卷内容原样保留）。
7. **健康检查** — 最多等 30 次（间隔 4 秒）直到 `/healthz` 返回 200，超时不阻塞主流程。
8. **验收** — `docker ps` + `curl /healthz` + `curl /site/`。

## 注意事项

- **密码安全**：脚本用 `-S -p '' bash -lc` 方式给 sudo 喂密码，**密码不会出现在 stdout**。日志中会把密码替换成 `******`。
- **临时包位置**：打包产物放在系统临时目录（`%TEMP%\pear-src-*.tar.gz`），项目根不留残留。
- **构建失败处理**：源码已更新到远端，但容器仍在跑旧镜像；下次重新跑一次就行。
- **NAS 防火墙**：确保本机到 NAS 的 22 端口可达（已验证 ping 连通）。

## 故障排查

| 现象 | 可能原因 | 处理 |
|------|----------|------|
| `paramiko 未找到` | 未安装 | 用管理 python 装一次 `pip install paramiko` |
| `docker: command not found` | sudo 没带 sudoers | 确认 NAS 上 `bwadmin` 有 `sudo` 权限（`sudo -S -p '' bash -lc whoami` 能输 `root`）|
| `ImageBuildError: python:3.11-slim: 401` | `--pull` 强制拉取 | 去掉 `--pull`，NAS 已有本地缓存 |
| 构建后模板未生效 | Docker 层缓存命中 | 加 `--no-cache` 强制重建 |
| 图标仍是字母头像 | 未同步种子 | 运行 `--icons-only`，或手动把 `data/icon/*.ico` 拷进 NAS 同目录 |
| 容器启动后 healthz 不 200 | 数据库迁移缺失 | 进容器跑 `flask db upgrade` |

## 依赖此脚本的其他命令

```bash
# 查看 NAS 上当前容器状态（不动任何东西）
SSH_PASS=peng4077 python deploy/nas/deploy.py --check

# 看本地源包里实际有什么
SSH_PASS=peng4077 python deploy/nas/deploy.py --pack-only
```