crypto_key/DEPLOY.md

部署文档 — crypto_key（Ubuntu /opt）

仓库：https://git.bz121.com/dekun/crypto_key
部署路径：/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 克隆仓库

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

3.2 配置环境变量

cp .env.example .env

编辑 .env（若留占位符，首次启动会自动生成合法密钥）：

变量	说明
SECRET_KEY	Flask 会话密钥，随机长字符串
AUTH_USERNAME	登录用户名
AUTH_PASSWORD	登录密码（保存为哈希）
DATA_ENCRYPTION_KEY	Fernet 密钥，用于加密 data.json

生成 Fernet 密钥：

python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

3.3 一键安装并启动

sudo bash scripts/install-ubuntu.sh

脚本将：安装系统依赖 → 创建 venv → pip install → PM2 启动 → pm2 save。

3.4 验证

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

hostname -I | awk '{print $1}'

首次登录默认可能是 admin / admin123，请登录后在 系统设置 中修改。

---

四、手动部署（逐步）

4.1 系统依赖

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 环境

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 启动

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 开机自启

pm2 startup
# 按提示执行输出的 sudo 命令
pm2 save

4.6 目录权限（推荐）

sudo chown -R $USER:$USER /opt/crypto_key
chmod 600 /opt/crypto_key/.env /opt/crypto_key/data.json 2>/dev/null || true

---

五、Windows 本地部署

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 守护（可选）：

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 内解释器）。

---

七、更新升级

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。

---

八、备份与恢复

8.1 必须备份的文件

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 迁移到新服务器

# 旧服务器打包
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，局域网可访问。建议限制来源：

# 仅允许局域网段（示例）
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           # 更新说明

---

十二、命令速查

# 首次部署
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。