# 部署指南（M5）

ws_usernode 交付形态：**单 Go 二进制**（前端已 go:embed 嵌入），配 systemd 服务 +
sudoers 白名单。可选 podman 容器镜像。本文件覆盖完整生产部署步骤与验证。

---

## 1. 构建

前置：Go ≥ 1.22、podman（构建前端需要容器，宿主机 Node 版本过旧无法直接构建）。

```bash
# 1) 构建前端并嵌入 go:embed（内部自动 podman 构建 dev 镜像 + npm install + vite build）
make web-build

# 2) 编译含前端产物的单二进制
make build-embed        # 产物 bin/usernode
```

> 代理环境：容器构建无法继承 proxychains，Makefile 通过 `--build-arg` 传递
> `HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY`。若宿主机 LD_PRELOAD 了
> proxychains（本环境如此），podman 拉取镜像会失败，需：
> `env -u LD_PRELOAD -u PROXYCHAINS_CONF_FILE make web-build`

验证二进制：`./bin/usernode --help`；健康检查 `curl localhost:8080/healthz`。

---

## 2. systemd 部署（推荐）

### 2.1 运行用户与目录

```bash
sudo useradd -r -s /usr/sbin/nologin -d /var/lib/usernode usernode
sudo mkdir -p /var/lib/usernode /var/log/usernode /etc/usernode
sudo chown usernode:usernode /var/lib/usernode /var/log/usernode
```

### 2.2 安装二进制与配置

```bash
sudo install -o usernode -g usernode -m 0755 bin/usernode /usr/local/bin/usernode
sudo install -o root -g root -m 0644 config.example.toml /etc/usernode/config.toml
sudoedit /etc/usernode/config.toml
```

配置要点（生产）：

```toml
[app]
env = "production"
base_url = "https://usernode.example.com"   # 对外地址（邮件重置链接）

[server]
listen = "127.0.0.1:8080"                    # 置于反向代理后；或直接 0.0.0.0
trusted_proxies = ["127.0.0.1", "::1"]

[database]
driver = "mysql"                             # 生产 MySQL；小规模可 sqlite
dsn = "usernode:pass@tcp(127.0.0.1:3306)/usernode?charset=utf8mb4&parseTime=True&loc=UTC"

[smtp]
host = "smtp.example.com"                    # 邮件必配（OTP/审批/到期通知）
port = 587
username = "usernode"
password = "..."                             # 或 USERNODE_SMTP_PASSWORD 环境变量
from = "usernode@example.com"

[system]
sudo = true                                  # 必须 true：经 sudo -n 白名单执行
dry_run = false                              # 必须 false

[audit]
archive_dir = "/var/lib/usernode/audit_archive"   # 审计每日归档；留空不清理
```

### 2.3 sudoers 白名单

```bash
sudo cp deploy/sudoers.example /etc/sudoers.d/usernode
sudo visudo -c
```

白名单仅允许 `useradd/usermod/userdel/passwd/mkdir/chmod/chown/install`
（禁任意 shell），命令参数由程序内强校验。

### 2.4 初始化数据库与管理员

```bash
sudo -u usernode usermode migrate --config /etc/usernode/config.toml    # 建表（先于 admin create）
sudo -u usernode usernode admin create --config /etc/usernode/config.toml \
    --username root --password '强密码' --email admin@example.com
```

### 2.5 安装服务并启动

```bash
sudo install -o root -g root -m 0644 deploy/usernode.service /etc/systemd/system/usernode.service
sudo systemctl daemon-reload
sudo systemctl enable --now usernode
sudo systemctl status usernode
journalctl -u usernode -f          # 结构化日志（slog）
```

### 2.6 反向代理（TLS 可选但建议）

nginx 示例：

```nginx
server {
    listen 443 ssl;
    server_name usernode.example.com;
    # ssl_certificate / ssl_certificate_key ...
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

---

## 3. podman 容器（可选）

```bash
make image                 # 多阶段构建：node 构建前端 → Go 编译 → alpine 运行镜像
podman run -d --name usernode \
  -p 8080:8080 \
  -v usernode-data:/data \
  -v /etc/usernode:/etc/usernode:ro \
  -e USERNODE_SYSTEM_SUDO=true \
  -e USERNODE_SYSTEM_DRY_RUN=false \
  ws-usernode:0.3.0-m5
```

> 容器内系统账号操作：容器以 usernode 用户运行，需在宿主机（或特权容器内）
> 配置对应 sudoers；默认 `dry_run=true` 只打印计划命令，用于容器内演练。
> 容器内用户目录/系统账号与宿主机共享时，请自行评估 sudo 与挂载边界。

---

## 4. SQLite → MySQL 迁移

```bash
# 前置：MySQL 已建库、建账号；可先用指向 MySQL 的配置跑 usernode migrate 建表
MYSQL_DSN='usernode:pass@tcp(127.0.0.1:3306)/usernode?charset=utf8mb4&parseTime=True&loc=UTC' \
  ./deploy/migrate-sqlite2mysql.sh /path/to/usernode.db
```

脚本会导出 SQLite（结构+数据）、改写为 MySQL 兼容语法并导入，最后逐表比对行数。
详见脚本头部注释（含时间字段精度说明）。

---

## 5. 验收清单（对照 PLAN M5 验收标准）

- [ ] 管理员创建用户 → 外部用户图形验证码 + OTP（邮件或 CLI）登录 → 上传公钥 → SSH 登录服务器
- [ ] 吊销密钥立即失效；到期自动禁用并通知；回收期内可延期，超期自动回收（保留审计）
- [ ] 所有管理操作可审计、可查询、可 CSV 导出；每日归档（配置 archive_dir 后）
- [ ] SQLite 数据可迁移至 MySQL（deploy/migrate-sqlite2mysql.sh）
- [ ] 单二进制部署（systemd + sudoers 白名单）通过
- [ ] podman 容器构建通过

## 6. 运维速查

| 场景 | 操作 |
|---|---|
| 重置管理员密码 | `sudo -u usernode usernode admin reset-password --config /etc/usernode/config.toml --username root --password 新密码` |
| 获取外部用户 OTP | `usernode user otp --config ... --username ext_xxx`（与邮件同码同效期） |
| 查看审计归档 | `ls /var/lib/usernode/audit_archive/` |
| 查看邮件失败记录 | 数据库 `mail_logs` 表 status='failed'（每 5 分钟自动重试） |
| 手动触发维护 | 重启服务触发 `@daily` 维护；或等待 `@every 6h` 补扫 |
| 备份 | SQLite：停服拷贝 db 文件；MySQL：mysqldump |