Initial commit: crypto_key API key manager with PM2 and Ubuntu deploy docs

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-19 00:54:27 +08:00
commit 0203a65973
14 changed files with 1140 additions and 0 deletions
@@ -0,0 +1,287 @@
+# 部署文档 — 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
+```