dekun
319 lines
7.5 KiB
Markdown
319 lines
7.5 KiB
Markdown
# 部署文档 — 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)**。
|