dekun/crypto_key
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新md

Browse Source
This commit is contained in:
dekun
2026-05-27 07:45:16 +08:00
parent 1f695799bf
commit 703fd912f8
4 changed files with 652 additions and 388 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEPLOY.md
+318 -307
View File
@@ -1,307 +1,318 @@
# 部署文档 — 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`，无登录，监听 `0.0.0.0:5200`（本机 + 局域网可访问）。
---
## 一、架构
```
浏览器（本机或局域网） → http://<服务器IP>: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
```
访问地址：
| 场景 | 地址 |
|------|------|
| 服务器本机 | http://127.0.0.1:5200 |
| 局域网其他设备 | `http://<局域网IP>:5200` |
查看服务器局域网 IP：
```bash
hostname -I | awk '{print $1}'
# 或
ip -4 addr show | grep -oP '(?<=inet\s)\d+(\.\d+){3}' | grep -v 127.0.0.1
```
示例：若 IP 为 `192.168.1.100`，手机/电脑在同一 WiFi 下访问 **http://192.168.1.100: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` |
| 局域网无法访问 | 检查防火墙是否放行 5200；`sudo ufw allow 5200/tcp` |
| 无法访问页面 | `pm2 logs api-key-manager`；确认 `ss -tlnp \| grep 5200` 显示 `0.0.0.0:5200` |
| 更新后异常 | `pip install -r requirements.txt` 后 `pm2 restart api-key-manager` |
---
## 十、安全说明
- 服务绑定 **0.0.0.0:5200**，同一局域网内设备均可访问。
- **无登录鉴权**，切勿将端口映射到公网或暴露于不可信网络。
- `data.json` 已加入 `.gitignore`，不会推送到仓库。
- 建议：仅在家/办公室可信局域网使用；云服务器请配合防火墙限制来源 IP。
### 防火墙（Ubuntu）
```bash
# 仅允许局域网网段访问（示例 192.168.0.0/16）
sudo ufw allow from 192.168.0.0/16 to any port 5200 proto tcp
# 或临时开放（测试用，范围更大）
sudo ufw allow 5200/tcp
```
---
## 十一、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
```
# 部署文档 — crypto_key（Ubuntu /opt）
> 仓库：[https://git.bz121.com/dekun/crypto_key](https://git.bz121.com/dekun/crypto_key.git)
> 部署路径：**`/opt/crypto_key`**
> 进程守护：**PM2** · 端口：**5200**
---
## 一、架构说明
```
浏览器（本机 / 局域网）
→ http://<IP>:5200
→ PM2 (api-key-manager)
→ venv/python app.py (Flask)
→ .env （登录账号 + 加密主密钥）
→ data.json （加密后的凭证数据）
→ settings.json （自定义类型配置）
```
| 文件 | 说明 | 是否提交 Git |
|------|------|----------------|
| `.env` | `SECRET_KEY`、`AUTH_*`、`DATA_ENCRYPTION_KEY` | 否 |
| `data.json` | 加密凭证库 | 否 |
| `settings.json` | 自定义类型定义 | 否（建议备份） |
| `venv/` | Python 虚拟环境 | 否 |
---
## 二、环境要求
| 项目 | 要求 |
|------|------|
| 系统 | Ubuntu 20.04 / 22.04 / 24.04 LTS（Windows 见附录） |
| Python | 3.8+ |
| Node.js | 16+（PM2 守护时需要） |
| 权限 | `sudo`（一键安装脚本） |
| 磁盘 | ≥ 200MB |
### Python 依赖
```
flask>=3.0.0
python-dotenv>=1.0.0
cryptography>=42.0.0
werkzeug>=3.0.0
```
---
## 三、首次部署（Ubuntu 推荐）
### 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
cp .env.example .env
```
编辑 `.env`（若留占位符，首次启动会自动生成合法密钥）：
| 变量 | 说明 |
|------|------|
| `SECRET_KEY` | Flask 会话密钥，随机长字符串 |
| `AUTH_USERNAME` | 登录用户名 |
| `AUTH_PASSWORD` | 登录密码（保存为哈希） |
| `DATA_ENCRYPTION_KEY` | Fernet 密钥，用于加密 data.json |
生成 Fernet 密钥：
```bash
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```
### 3.3 一键安装并启动
```bash
sudo bash scripts/install-ubuntu.sh
```
脚本将：安装系统依赖 → 创建 `venv` → `pip install` → PM2 启动 → `pm2 save`。
### 3.4 验证
```bash
pm2 status
# api-key-manager 应为 online
curl -s http://127.0.0.1:5200/api/auth/status
# {"logged_in":false}
```
浏览器访问：
| 场景 | 地址 |
|------|------|
| 服务器本机 | http://127.0.0.1:5200 |
| 局域网 | `http://<服务器IP>:5200` |
```bash
hostname -I | awk '{print $1}'
```
首次登录默认可能是 `admin` / `admin123`，请登录后在 **系统设置** 中修改。
---
## 四、手动部署（逐步）
### 4.1 系统依赖
```bash
sudo apt update
sudo apt install -y python3 python3-venv python3-pip git curl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g pm2
```
### 4.2 Python 环境
```bash
cd /opt/crypto_key
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
### 4.3 配置 .env
见第三节 3.2。
### 4.4 PM2 启动
```bash
cd /opt/crypto_key
mkdir -p logs
chmod +x pm2-start.sh pm2-stop.sh
./pm2-start.sh
# 或: pm2 start ecosystem.config.cjs && pm2 save
```
### 4.5 开机自启
```bash
pm2 startup
# 按提示执行输出的 sudo 命令
pm2 save
```
### 4.6 目录权限（推荐）
```bash
sudo chown -R $USER:$USER /opt/crypto_key
chmod 600 /opt/crypto_key/.env /opt/crypto_key/data.json 2>/dev/null || true
```
---
## 五、Windows 本地部署
```powershell
cd C:\path\to\crypto_key
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
# 编辑 .env 或首次运行 python app.py 自动生成
python app.py
```
PM2 守护（可选）：
```powershell
npm install -g pm2
.\pm2-start.ps1
```
---
## 六、PM2 运维
| 命令 | 说明 |
|------|------|
| `pm2 status` | 查看状态 |
| `pm2 logs api-key-manager` | 查看日志 |
| `pm2 restart api-key-manager` | 重启 |
| `pm2 stop api-key-manager` | 停止 |
| `./pm2-start.sh` | 启动（Linux） |
| `.\pm2-start.ps1` | 启动（Windows） |
配置文件：`ecosystem.config.cjs`（进程名 `api-key-manager`，Python 使用 `venv` 内解释器）。
---
## 七、更新升级
```bash
cd /opt/crypto_key
cp data.json data.json.bak.$(date +%F)
cp .env .env.bak.$(date +%F)
git pull
source venv/bin/activate
pip install -r requirements.txt
pm2 restart api-key-manager
```
升级说明与破坏性变更见 [CHANGELOG.md](./CHANGELOG.md)。
---
## 八、备份与恢复
### 8.1 必须备份的文件
```bash
sudo cp /opt/crypto_key/.env /opt/crypto_key/.env.bak
sudo cp /opt/crypto_key/data.json /opt/crypto_key/data.json.bak
sudo cp /opt/crypto_key/settings.json /opt/crypto_key/settings.json.bak 2>/dev/null || true
```
### 8.2 恢复
1. 将 `.env`、`data.json`、`settings.json` 放回项目根目录。
2. **`.env` 中的 `DATA_ENCRYPTION_KEY` 必须与备份时一致**，否则无法解密。
3. `pm2 restart api-key-manager`。
### 8.3 迁移到新服务器
```bash
# 旧服务器打包
tar czvf crypto_key_backup.tar.gz .env data.json settings.json
# 新服务器克隆代码后解压到 /opt/crypto_key/
tar xzvf crypto_key_backup.tar.gz -C /opt/crypto_key/
# 再执行 venv 安装与 PM2 启动
```
---
## 九、防火墙
服务监听 **0.0.0.0:5200**，局域网可访问。建议限制来源：
```bash
# 仅允许局域网段（示例）
sudo ufw allow from 192.168.0.0/16 to any port 5200 proto tcp
# 或测试时临时开放
sudo ufw allow 5200/tcp
```
**切勿**将 5200 端口直接暴露到公网；务必启用登录并修改默认密码。
---
## 十、故障排查
| 现象 | 处理 |
|------|------|
| PM2 `errored` | `pm2 logs api-key-manager --err`；检查 `venv` 与依赖 |
| 无法登录 | 检查 `.env` 中 `AUTH_*`；删除错误密码哈希后重启，用自动生成默认账号 |
| 数据无法解密 | `DATA_ENCRYPTION_KEY` 是否与备份一致 |
| 局域网无法访问 | `ss -tlnp \| grep 5200` 应显示 `0.0.0.0:5200`；检查 ufw |
| 401 未登录 | 重新登录；检查 `SECRET_KEY` 是否被改动（会导致 Session 失效） |
| 旧明文 data.json | 启动后自动迁移；迁移前务必备份 |
---
## 十一、目录结构
```
/opt/crypto_key/
├── app.py # Flask 入口
├── storage.py # 加密存储与迁移
├── env_config.py # .env 读写
├── index.html # 前端（登录 + 主界面 + 设置）
├── requirements.txt
├── ecosystem.config.cjs # PM2
├── .env.example
├── settings.json # 自定义类型（运行时）
├── scripts/
│ └── install-ubuntu.sh
├── pm2-start.sh / pm2-stop.sh
├── pm2-start.ps1 / pm2-stop.ps1 / pm2-restart.ps1
├── logs/
├── venv/
├── README.md
├── USAGE.md # 使用说明
├── DEPLOY.md # 本文档
└── CHANGELOG.md # 更新说明
```
---
## 十二、命令速查
```bash
# 首次部署
sudo git clone https://git.bz121.com/dekun/crypto_key.git /opt/crypto_key
cd /opt/crypto_key && cp .env.example .env && sudo bash scripts/install-ubuntu.sh
# 日常
pm2 status
pm2 restart api-key-manager
pm2 logs api-key-manager --lines 50
```
使用细节请参阅 **[USAGE.md](./USAGE.md)**。