# 部署文档 — crypto_key（Ubuntu /opt）

> 仓库：[https://git.bz121.com/dekun/crypto_key](https://git.bz121.com/dekun/crypto_key.git)  
> 部署路径：**`/opt/crypto_key`**  
> 进程守护：**PM2** · 端口：**5200**  
> **代码更新一律使用 `git pull`，严禁 scp**

---

## 一、架构说明

```
浏览器（本机 / 局域网）
    → http://<IP>:5200
        → PM2 (api-key-manager)
            → venv/python app.py (Flask)
                → .env          （登录账号 + 加密主密钥）
                → data.json     （加密后的凭证数据）
                → settings.json （自定义类型配置）
                → uploads/      （图片附件）
                → /root/crypto_key_backups/  （每日自动备份）
```

| 文件 | 说明 | 是否提交 Git |
|------|------|----------------|
| `.env` | `SECRET_KEY`、`AUTH_*`、`DATA_ENCRYPTION_KEY` | 否 |
| `data.json` | 加密凭证库 | 否 |
| `settings.json` | 自定义类型定义 | 否 |
| `uploads/` | 上传的图片 | 否 |
| `venv/` | Python 虚拟环境 | 否 |

---

## 二、环境要求

| 项目 | 要求 |
|------|------|
| 系统 | Ubuntu 20.04 / 22.04 / 24.04 LTS（Windows 见附录） |
| Python | 3.8+ |
| Node.js | 16+（PM2 守护时需要） |
| 权限 | `sudo`（管理脚本） |
| 磁盘 | ≥ 200MB |

---

## 三、交互式一键部署（推荐）

### 3.1 克隆仓库

```bash
sudo mkdir -p /opt
sudo git clone https://git.bz121.com/dekun/crypto_key.git /opt/crypto_key
cd /opt/crypto_key
```

### 3.2 运行管理脚本

```bash
sudo bash scripts/manage.sh
```

交互菜单：

```
1) 一键部署
2) 更新（git pull，严禁 scp）
3) 一键卸载
0) 退出
```

也可直接传参：

```bash
sudo bash scripts/manage.sh deploy      # 等同选项 1
sudo bash scripts/manage.sh update      # 等同选项 2
sudo bash scripts/manage.sh uninstall   # 等同选项 3
```

兼容旧入口：`sudo bash scripts/install-ubuntu.sh`（内部调用 deploy）。

### 3.3 部署脚本会做什么

1. 安装 python3 / venv / git / Node / PM2  
2. `git clone` 或 **`git pull`** 到 `/opt/crypto_key`  
3. 创建 venv、`pip install -r requirements.txt`  
4. 配置每日 03:00 cron 备份到 `/root/crypto_key_backups/`  
5. PM2 启动 `api-key-manager`  

### 3.4 验证

```bash
pm2 status
curl -s http://127.0.0.1:5200/api/auth/status
# {"logged_in":false}
```

浏览器：`http://127.0.0.1:5200` 或 `http://<服务器IP>:5200`  
默认可能是 `admin` / `admin123`，请尽快修改。

---

## 四、更新升级（仅 git pull）

```bash
cd /opt/crypto_key
sudo bash scripts/manage.sh
# 选择 2) 更新
```

脚本流程：更新前自动备份 → `git pull` → 安装依赖 → 刷新 cron → 重启 PM2。

**禁止** 使用 scp / rsync 覆盖代码目录；数据文件（`.env`、`data.json`）本来就不在 Git 里，不会被 pull 冲掉。

手动更新：

```bash
cd /opt/crypto_key
git pull
source venv/bin/activate
pip install -r requirements.txt
pm2 restart api-key-manager
```

---

## 五、一键卸载

```bash
sudo bash scripts/manage.sh
# 选择 3) 一键卸载，输入 yes 确认
```

会停止 PM2、移除 cron、删除 `/opt/crypto_key`；卸载前尽量再打一份包到 `/root/crypto_key_backups/`，**保留备份目录**。

---

## 六、Windows 本地部署

```powershell
cd C:\path\to\crypto_key
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
python app.py
```

自动备份目录回退为项目下 `backups\`（无 `/root` 写权限时）。

---

## 七、PM2 运维

| 命令 | 说明 |
|------|------|
| `pm2 status` | 查看状态 |
| `pm2 logs api-key-manager` | 查看日志 |
| `pm2 restart api-key-manager` | 重启 |
| `./pm2-start.sh` | 启动（Linux） |

---

## 八、备份与恢复

### 8.1 自动备份

- 应用内守护线程：每天 **03:00**  
- cron（部署脚本安装）：每天 **03:00**  
- 目录：`/root/crypto_key_backups/crypto_key_backup_YYYYMMDD_HHMMSS.tar.gz`  
- 保留约 30 天，过期自动清理  

### 8.2 前端备份恢复

系统设置 → **备份恢复**：

- 下载备份  
- 立即备份到服务器  
- 上传 `.tar.gz` 恢复  

备份内容：`.env`、`data.json`、`settings.json`、`uploads/`。

### 8.3 命令行恢复

```bash
# 解压到项目目录（示例）
cd /opt/crypto_key
tar xzvf /root/crypto_key_backups/某备份.tar.gz
pm2 restart api-key-manager
```

**`.env` 中 `DATA_ENCRYPTION_KEY` 必须与备份一致。**

---

## 九、防火墙

```bash
sudo ufw allow from 192.168.0.0/16 to any port 5200 proto tcp
```

切勿将 5200 直接暴露公网。

---

## 十、故障排查

| 现象 | 处理 |
|------|------|
| PM2 `errored` | `pm2 logs api-key-manager --err` |
| 无法登录 | 检查 `.env` 中 `AUTH_*` |
| 数据无法解密 | `DATA_ENCRYPTION_KEY` 是否与备份一致 |
| 局域网无法访问 | `ss -tlnp \| grep 5200`；检查 ufw |
| 图片 404 | 确认 `uploads/` 存在且备份已含图片文件 |

---

## 十一、目录结构

```
/opt/crypto_key/
├── app.py
├── storage.py
├── backup.py
├── env_config.py
├── index.html
├── requirements.txt
├── ecosystem.config.cjs
├── scripts/
│   ├── manage.sh           # 交互式：部署 / 更新 / 卸载
│   └── install-ubuntu.sh   # 兼容入口 → deploy
├── uploads/                # 图片（运行时）
├── logs/
├── venv/
└── ...
```

---

## 十二、命令速查

```bash
# 首次
sudo git clone https://git.bz121.com/dekun/crypto_key.git /opt/crypto_key
cd /opt/crypto_key && sudo bash scripts/manage.sh   # 选 1

# 更新（git pull only）
sudo bash scripts/manage.sh   # 选 2

# 卸载
sudo bash scripts/manage.sh   # 选 3
```

使用细节请参阅 **[USAGE.md](./USAGE.md)**。