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

> 仓库地址：[https://git.bz121.com/dekun/crypto_key](https://git.bz121.com/dekun/crypto_key.git)  
> 部署路径：**`/opt/crypto_key`**  
> 进程守护：**PM2** · 服务端口：**5200**

币圈 API 密钥本地管理工具。数据保存在服务器本地 `data.json`，无登录，默认仅监听 `127.0.0.1`。

---

## 一、架构

```
浏览器 / SSH 隧道 → http://127.0.0.1:5200
                        ↓
                   PM2 (api-key-manager)
                        ↓
              /opt/crypto_key/venv/python app.py
                        ↓
              /opt/crypto_key/data.json
```

| 路径 | 说明 |
|------|------|
| `/opt/crypto_key` | 项目根目录（从 Git 克隆） |
| `/opt/crypto_key/data.json` | 账户数据（不纳入 Git） |
| `/opt/crypto_key/logs/` | PM2 日志 |
| `/opt/crypto_key/venv/` | Python 虚拟环境 |

---

## 二、服务器要求

| 项目 | 要求 |
|------|------|
| 系统 | Ubuntu 20.04 / 22.04 / 24.04 LTS |
| 权限 | 具备 `sudo` 的普通用户或 root |
| Python | 3.8+（`python3`） |
| Node.js | 16+（用于 PM2） |
| 磁盘 | ≥ 100MB |

---

## 三、首次部署（推荐：一键脚本）

### 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
sudo bash scripts/install-ubuntu.sh
```

脚本将自动完成：安装 `python3` / `git` / `Node.js` / `PM2` → 创建 `venv` → 安装 Flask → PM2 启动服务。

### 3.2 验证

```bash
pm2 status
curl -s http://127.0.0.1:5200/api/accounts
```

浏览器或 SSH 端口转发访问：**http://127.0.0.1:5200**

```bash
# 本机 SSH 转发示例（在你自己的电脑上执行）
ssh -L 5200:127.0.0.1:5200 user@your-server-ip
# 然后浏览器打开 http://127.0.0.1:5200
```

---

## 四、手动部署（逐步）

适合需要自定义权限或不用一键脚本的环境。

### 4.1 安装系统依赖

```bash
sudo apt update
sudo apt install -y python3 python3-venv python3-pip git curl

# Node.js + PM2
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g pm2
```

### 4.2 克隆到 /opt

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

若目录已存在，更新代码：

```bash
cd /opt/crypto_key
sudo git pull
```

### 4.3 Python 环境

```bash
cd /opt/crypto_key
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 4.4 PM2 启动

```bash
cd /opt/crypto_key
mkdir -p logs
chmod +x pm2-start.sh pm2-stop.sh
./pm2-start.sh
```

或：

```bash
pm2 start ecosystem.config.cjs
pm2 save
```

### 4.5 目录权限（可选）

若用普通用户运行 PM2，建议将项目目录属主改为该用户：

```bash
sudo chown -R $USER:$USER /opt/crypto_key
```

---

## 五、开机自启

```bash
pm2 startup
# 终端会输出一行 sudo 命令，复制并执行
pm2 save
```

重启后检查：

```bash
pm2 status
# api-key-manager 应为 online
```

---

## 六、日常运维

### 查看状态与日志

```bash
pm2 status
pm2 logs api-key-manager
pm2 logs api-key-manager --lines 100
```

### 重启 / 停止

```bash
cd /opt/crypto_key
./pm2-start.sh          # 启动
# 或
pm2 restart api-key-manager

./pm2-stop.sh           # 停止
# 或
pm2 stop api-key-manager
```

### 更新代码

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

### 备份数据

```bash
sudo cp /opt/crypto_key/data.json /opt/crypto_key/data.json.bak.$(date +%F)
```

`data.json` 含明文 API 密钥，请加密存储或限制文件权限：

```bash
chmod 600 /opt/crypto_key/data.json
```

---

## 七、PM2 配置说明

文件：`/opt/crypto_key/ecosystem.config.cjs`

| 配置 | 值 |
|------|-----|
| 进程名 | `api-key-manager` |
| 工作目录 | 项目根目录（自动） |
| Python | `venv/bin/python` |
| 自动重启 | 是 |
| 日志 | `logs/pm2-out.log` / `logs/pm2-error.log` |

---

## 八、项目文件结构

```
/opt/crypto_key/
├── app.py
├── index.html
├── requirements.txt
├── ecosystem.config.cjs
├── pm2-start.sh
├── pm2-stop.sh
├── scripts/
│   └── install-ubuntu.sh
├── logs/
├── venv/
├── data.json          # 运行时生成，已 .gitignore
├── README.md
└── DEPLOY.md
```

---

## 九、故障排查

| 现象 | 处理 |
|------|------|
| `pm2 status` 为 errored | `pm2 logs api-key-manager --err`；确认 `venv` 已创建 |
| 端口 5200 占用 | `sudo ss -tlnp \| grep 5200`；修改 `app.py` 中 `port` 后 `pm2 restart` |
| `git clone` 需认证 | 配置 SSH Key 或 `git config credential.helper store` |
| 无法访问页面 | 服务仅监听 127.0.0.1，需 SSH 隧道或在本机 curl |
| 更新后异常 | `pip install -r requirements.txt` 后 `pm2 restart api-key-manager` |

---

## 十、安全说明

- 默认绑定 **127.0.0.1**，不对外网直接暴露。
- **无登录鉴权**，切勿将 `0.0.0.0:5200` 开放到公网。
- `data.json` 已加入 `.gitignore`，不会推送到仓库。
- 建议在防火墙仅允许 SSH，通过隧道访问管理页。

---

## 十一、Windows 本地开发（附录）

```powershell
cd C:\path\to\crypto_key
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
npm install -g pm2
.\pm2-start.ps1
```

访问：http://127.0.0.1:5200

---

## 十二、命令速查

```bash
# 首次部署
sudo git clone https://git.bz121.com/dekun/crypto_key.git /opt/crypto_key
cd /opt/crypto_key && sudo bash scripts/install-ubuntu.sh

# 日常
pm2 status
pm2 restart api-key-manager
cd /opt/crypto_key && git pull && pm2 restart api-key-manager
```