From 703fd912f855f80214937f018a1f4279e1cc3da6 Mon Sep 17 00:00:00 2001
From: dekun <dekun@local>
Date: Wed, 27 May 2026 07:45:16 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md | 105 +++++++++
 DEPLOY.md    | 625 ++++++++++++++++++++++++++-------------------------
 README.md    | 126 ++++-------
 USAGE.md     | 184 +++++++++++++++
 4 files changed, 652 insertions(+), 388 deletions(-)
 create mode 100644 CHANGELOG.md
 create mode 100644 USAGE.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..ed6aa5e
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,105 @@
+# 更新说明 — crypto_key
+
+本文档记录各版本功能变更与升级注意事项。
+
+---
+
+## v2.0.0（当前）
+
+### 新增
+
+- **登录系统**：用户名 + 密码（单用户），凭据保存在 `.env`
+- **数据加密**：`data.json` 使用 Fernet（AES）加密存储，密钥为 `DATA_ENCRYPTION_KEY`（`.env`）
+- **凭证类型扩展**：
+  - 交易所 API（Binance / OKX / Gate）
+  - 网站账号（网址可点击）
+  - 邮箱账户（mailto / 网页登录链接）
+  - 企业微信机器人、钉钉机器人
+  - 微信（微信号 + 手机号）、QQ（QQ 号 + 手机号）
+- **自定义类型**：系统设置中自行添加字段（如小红书、抖音、快手）
+- **系统设置页**：
+  - 修改登录用户名/密码（写入 `.env`）
+  - 管理自定义类型（增删、搜索）
+- **查询机制**：添加后不自动展示；按类型 + 关键词 +「确认」后显示
+- **类型搜索**：添加/查询时支持输入过滤类型
+- **旧数据迁移**：明文 `data.json` 首次加载自动转为加密格式
+
+### 变更
+
+- 监听地址由 `127.0.0.1` 改为 **`0.0.0.0`**，支持局域网访问
+- API 主路径由 `/api/accounts` 扩展为 `/api/credentials`（保留旧路径兼容）
+- 数据模型由固定 `username/api_key/api_secret` 改为 `type_id + fields` 结构
+- 依赖增加：`python-dotenv`、`cryptography`、`werkzeug`
+
+### 安全
+
+- 浏览器 **不** 使用 localStorage/sessionStorage 存储明文
+- Session Cookie 设置 `HttpOnly`、`SameSite=Lax`
+- `.env`、`data.json`、`settings.json` 默认加入 `.gitignore`
+
+### 升级注意（从 v1.x 升级）
+
+1. 备份现有 `data.json`：
+   ```bash
+   cp data.json data.json.bak
+   ```
+2. 安装新依赖：
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. 配置 `.env`（可复制 `.env.example`，或首次运行自动生成）：
+   - `SECRET_KEY`
+   - `AUTH_USERNAME` / `AUTH_PASSWORD`
+   - `DATA_ENCRYPTION_KEY`
+4. 启动服务，旧明文数据将 **自动迁移** 为加密格式。
+5. 使用默认或自定义账号登录，在「系统设置」中修改密码。
+6. PM2 用户执行：`pm2 restart api-key-manager`
+
+> **重要**：升级后切勿删除或修改 `.env` 中的 `DATA_ENCRYPTION_KEY`，否则无法解密已有数据。
+
+---
+
+## v1.2.0
+
+### 新增
+
+- 交易所下拉：Binance / OKX / Gate
+- OKX 专用 Passphrase 字段
+- 按交易所查询（下拉 + 确认）
+- 添加成功后默认不展示列表
+- 敏感字段打码显示（复制仍为明文）
+
+### 变更
+
+- 支持局域网访问（`0.0.0.0:5200`）
+
+---
+
+## v1.1.0
+
+### 新增
+
+- PM2 守护进程支持（`ecosystem.config.cjs`）
+- Ubuntu `/opt/crypto_key` 部署脚本与文档
+- 启动脚本：`pm2-start.sh` / `pm2-start.ps1`
+
+---
+
+## v1.0.0
+
+### 初始功能
+
+- Flask 后端 + 单页前端（黑色主题）
+- 多账户 API 密钥管理：`username`、`api_key`、`api_secret`
+- 本地 `data.json` 明文存储
+- 每条记录三个复制按钮
+- 端口 5200，无登录
+
+---
+
+## 版本规划（待定）
+
+- [ ] 可选 HTTPS / 反向代理说明模板
+- [ ] 凭证编辑（当前仅支持添加、删除）
+- [ ] 导出/导入加密备份包
+- [ ] 登录失败次数限制
diff --git a/DEPLOY.md b/DEPLOY.md
index e16d073..a05a6e6 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -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)**。
diff --git a/README.md b/README.md
index 0239975..5bb7cc2 100644
--- a/README.md
+++ b/README.md
@@ -1,130 +1,94 @@
 # crypto_key — 凭证保险库
 
-本地 Web 工具，管理交易所 API、网站、邮箱、机器人、微信/QQ 及自定义类型凭证。数据 **AES 加密** 存入 `data.json`，登录凭据与加密主密钥在 `.env`。
+本地 / 局域网 Web 工具，集中管理交易所 API、网站、邮箱、机器人、微信/QQ 及自定义类型凭证。数据 **AES 加密** 存储，**用户名密码登录**，浏览器不缓存明文。
 
 | 项目 | 说明 |
 |------|------|
 | 仓库 | [git.bz121.com/dekun/crypto_key](https://git.bz121.com/dekun/crypto_key.git) |
-| Ubuntu 部署路径 | `/opt/crypto_key` |
-| 服务端口 | `5200` |
-| 进程守护 | PM2 |
+| 端口 | `5200`（`0.0.0.0`，局域网可访问） |
+| Ubuntu 部署 | `/opt/crypto_key` + PM2 |
 
 ---
 
-## 功能
+## 文档导航
 
-- **登录**：用户名 + 密码（`.env`），浏览器不缓存明文
-- **内置类型**：交易所 API、网站、邮箱、企业微信/钉钉机器人、微信、QQ
-- **自定义类型**：系统设置中添加（如小红书、抖音、快手）
-- **查询**：类型搜索 + 关键词 + 确认后显示；网站/邮箱可点击跳转
-- **旧 data.json**：首次启动自动迁移为加密格式
-- 黑色专业界面，列表展示 + 每项 3 个复制按钮（**复制始终为明文**）
-- 可选界面打码显示，不影响复制内容
-- 数据持久化至 `data.json`
+| 文档 | 说明 |
+|------|------|
+| **[USAGE.md](./USAGE.md)** | 使用说明（登录、添加、查询、系统设置） |
+| **[DEPLOY.md](./DEPLOY.md)** | 部署文档（Ubuntu/Windows、PM2、备份、排错） |
+| **[CHANGELOG.md](./CHANGELOG.md)** | 更新说明与版本升级注意 |
 
 ---
 
-## 首次配置
+## 快速开始
 
 ```bash
-cp .env.example .env
-# 编辑 .env：SECRET_KEY、AUTH_USERNAME、AUTH_PASSWORD、DATA_ENCRYPTION_KEY
+git clone https://git.bz121.com/dekun/crypto_key.git
+cd crypto_key
+python3 -m venv venv
+source venv/bin/activate          # Windows: venv\Scripts\activate
 pip install -r requirements.txt
+cp .env.example .env            # 可选，首次运行也会自动生成
 python app.py
 ```
 
-默认首次运行会自动生成 `.env`（用户名 `admin` / 密码 `admin123`，请立即在「系统设置」中修改）。
+浏览器打开：
 
-## Ubuntu 服务器部署（/opt）
+- 本机：http://127.0.0.1:5200  
+- 局域网：`http://<本机IP>:5200`  
 
-完整步骤见 **[DEPLOY.md](./DEPLOY.md)**。
+默认账号（请尽快在系统设置中修改）：`admin` / `admin123`
+
+---
+
+## 主要功能
+
+- 登录鉴权（凭据在 `.env`，Session 在服务端）
+- 内置类型：交易所、网站、邮箱、企微/钉钉机器人、微信、QQ
+- 自定义类型：系统设置中添加（小红书、抖音等）
+- 查询后显示 + 类型/关键词搜索 + 敏感字段打码（复制为明文）
+- 旧版明文 `data.json` 自动迁移加密
+
+---
+
+## Ubuntu 一键部署
 
 ```bash
 sudo git clone https://git.bz121.com/dekun/crypto_key.git /opt/crypto_key
 cd /opt/crypto_key
-cp .env.example .env   # 并编辑
+cp .env.example .env
 sudo bash scripts/install-ubuntu.sh
 ```
 
-访问：
-
-- 本机：**http://127.0.0.1:5200**
-- 局域网：**http://<服务器局域网IP>:5200**（如 `http://192.168.1.100:5200`）
-
-查看本机 IP：`hostname -I` 或 `ip addr`
-
-```bash
-pm2 status
-pm2 logs api-key-manager
-```
+详见 [DEPLOY.md](./DEPLOY.md)。
 
 ---
 
-## 本地开发
-
-```bash
-python3 -m venv venv
-source venv/bin/activate          # Windows: venv\Scripts\activate
-pip install -r requirements.txt
-python app.py
-```
-
-浏览器打开 http://127.0.0.1:5200（局域网内其他设备用 `http://<本机IP>:5200`）
-
-PM2 守护：`./pm2-start.sh`（Linux）或 `.\pm2-start.ps1`（Windows）
-
----
-
-## 文件说明
+## 项目文件
 
 | 文件 | 说明 |
 |------|------|
 | `app.py` | Flask 后端 |
-| `index.html` | 前端页面 |
+| `storage.py` | 加密存储与迁移 |
+| `env_config.py` | `.env` 管理 |
+| `index.html` | 前端单页 |
 | `ecosystem.config.cjs` | PM2 配置 |
-| `scripts/install-ubuntu.sh` | Ubuntu 一键安装 |
-| `DEPLOY.md` | 完整部署文档 |
-
----
-
-## 数据格式
-
-```json
-{
-  "id": "uuid",
-  "exchange": "binance",
-  "username": "账户名称",
-  "api_key": "API Key",
-  "api_secret": "API Secret",
-  "password": "仅 OKX 需要"
-}
-```
-
----
-
-## API
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/` | 前端页面 |
-| GET | `/api/accounts` | 获取全部账户 |
-| GET | `/api/accounts?exchange=binance` | 按交易所筛选 |
-| POST | `/api/accounts` | 新增账户 |
-| DELETE | `/api/accounts/<id>` | 删除账户 |
+| `scripts/install-ubuntu.sh` | Ubuntu 安装脚本 |
 
 ---
 
 ## 安全提示
 
-- 无认证，监听 `0.0.0.0`（局域网可访问），请勿暴露到公网；建议仅在可信局域网使用
-- `data.json` 为明文密钥，已 `.gitignore`，请定期备份
+- 仅在可信局域网使用，勿将 5200 映射到公网
+- 定期备份 `.env` 与 `data.json`（密钥丢失将无法解密）
+- 勿将 `.env`、`data.json` 提交到 Git
 
 ---
 
 ## 依赖
 
 ```
-flask>=3.0.0,<4.0.0
+flask, python-dotenv, cryptography, werkzeug
 ```
 
-服务器另需：Python 3.8+、Node.js（PM2）
+服务器 PM2 部署另需 Node.js 16+。
diff --git a/USAGE.md b/USAGE.md
new file mode 100644
index 0000000..3fea646
--- /dev/null
+++ b/USAGE.md
@@ -0,0 +1,184 @@
+# 使用说明 — crypto_key 凭证保险库
+
+本文档介绍日常使用方法。部署与安装请参阅 [DEPLOY.md](./DEPLOY.md)。
+
+---
+
+## 1. 产品简介
+
+**crypto_key** 是一款在浏览器中使用的本地/局域网凭证管理工具，用于集中保存：
+
+- 交易所 API（Binance、OKX、Gate）
+- 网站账号（可点击打开网址）
+- 邮箱账户（可点击发邮件或打开网页登录）
+- 企业微信 / 钉钉机器人 Webhook
+- 微信、QQ（微信号/QQ号 + 手机号）
+- 自定义类型（如小红书、抖音、快手等，在系统设置中自行添加）
+
+所有敏感数据在服务器上以 **加密形式** 写入 `data.json`；访问前需 **登录**。浏览器 **不会** 把密码写入 localStorage。
+
+| 项目 | 说明 |
+|------|------|
+| 默认端口 | 5200 |
+| 访问方式 | 本机 `http://127.0.0.1:5200` 或局域网 `http://<IP>:5200` |
+
+---
+
+## 2. 首次登录
+
+1. 启动服务后，在浏览器打开上述地址。
+2. 输入 **用户名** 和 **密码**。
+3. 首次部署时，若未配置 `.env`，系统可能自动生成默认账号：
+   - 用户名：`admin`
+   - 密码：`admin123`
+4. **登录后请立即进入「系统设置」修改用户名和密码。**
+
+> 登录状态保存在服务端 Session（HttpOnly Cookie），关闭浏览器后需重新登录（约 30 分钟无操作也会失效）。
+
+---
+
+## 3. 界面总览
+
+登录成功后主界面包含三块：
+
+| 区域 | 作用 |
+|------|------|
+| **添加凭证** | 选择类型、填写字段、保存 |
+| **查询凭证** | 按类型/关键词筛选，点击「确认」后展示列表 |
+| **凭证列表** | 展示查询结果；支持打码显示与复制 |
+
+右上角：
+
+- **系统设置**：修改登录账号、管理自定义类型
+- **退出**：清除登录状态
+
+---
+
+## 4. 添加凭证
+
+### 4.1 选择类型
+
+1. 在「添加凭证」区域的 **凭证类型** 输入框中输入关键字（如「交易所」「邮箱」「小红书」）。
+2. 从下拉列表中点击需要的类型。
+3. 下方会显示「已选：xxx」，并出现对应表单。
+
+### 4.2 各类型必填说明
+
+| 类型 | 主要字段 |
+|------|----------|
+| 交易所 API | 交易所、账户名称、API Key、API Secret；**OKX 额外必填 Passphrase 密码** |
+| 网站账号 | 名称、网址、用户名、密码 |
+| 邮箱账户 | 名称、邮箱地址、密码；可选网页登录地址 |
+| 企业微信机器人 | 名称、Webhook |
+| 钉钉机器人 | 名称、Webhook |
+| 微信 | 名称、微信号、手机号 |
+| QQ | 名称、QQ 号、手机号 |
+| 自定义类型 | 按你在系统设置中定义的字段填写 |
+
+### 4.3 提交
+
+1. 填写完成后点击 **「添加」**。
+2. 添加成功后会提示：**不会自动显示在列表中**。
+3. 需要到「查询凭证」区域选择类型并点击 **「确认」** 才能查看。
+
+---
+
+## 5. 查询凭证
+
+### 5.1 基本查询
+
+1. 在「查询凭证」中选择或搜索 **类型**（下拉框支持输入过滤）。
+2. （可选）在 **关键词** 中输入名称、账号、邮箱等片段。
+3. 若类型为 **交易所 API**，可再选 Binance / OKX / Gate。
+4. 点击右侧 **「确认」**。
+5. 列表显示该条件下所有记录。
+
+### 5.2 列表操作
+
+| 操作 | 说明 |
+|------|------|
+| **隐藏敏感字段** | 勾选后界面以圆点显示密码、Key 等；**复制按钮仍为真实明文** |
+| **复制** | 每条字段右侧「复制」按钮 |
+| **链接** | 网站「网址」、邮箱「邮箱地址」、邮箱「网页登录地址」可点击跳转 |
+| **删除** | 卡片右上角「删除」，需确认 |
+
+### 5.3 未查询时
+
+默认显示：「选择类型并点击「确认」查看」——不会展示任何凭证内容。
+
+---
+
+## 6. 系统设置
+
+点击右上角 **「系统设置」** 进入。
+
+### 6.1 修改登录账号（写入 .env）
+
+1. 填写 **新用户名**、**新密码**（至少 6 位）。
+2. 填写 **当前密码** 以确认身份。
+3. 点击 **「保存登录设置」**。
+4. 修改后请使用新账号重新登录。
+
+> 登录凭据保存在服务器 `.env` 文件中，不会出现在浏览器缓存。
+
+### 6.2 自定义凭证类型
+
+适用于小红书、抖音、快手等未内置的类型。
+
+**新增类型：**
+
+1. **类型 ID**：英文小写+下划线，如 `xiaohongshu`（创建后不可改）。
+2. **显示名称**：如 `小红书`。
+3. **字段列表**：点击「+ 添加字段」
+   - `key`：英文标识，如 `account`
+   - `显示名`：如 `账号`
+   - `类型`：文本 / 敏感 / 链接 / 邮箱 / 手机
+   - **必填**：是否必填
+4. 点击 **「保存自定义类型」**。
+
+**搜索 / 删除：**
+
+- 顶部搜索框可过滤已有自定义类型。
+- 「删除」会同时删除该类型下的 **所有凭证记录**。
+
+---
+
+## 7. 安全与使用建议
+
+1. **仅在可信局域网使用**，不要将 5200 端口映射到公网。
+2. **定期备份** `data.json` 和 `.env`（见 [DEPLOY.md](./DEPLOY.md) 备份章节）。
+3. **不要** 将 `.env`、`data.json` 提交到 Git 或发给他人。
+4. 若更换服务器，需同时拷贝 `.env` 与 `data.json`，否则无法解密数据。
+5. 复制敏感内容后，尽快粘贴使用，避免长时间留在系统剪贴板。
+
+---
+
+## 8. 常见问题
+
+**Q：登录提示用户名或密码错误？**  
+A：检查 `.env` 中 `AUTH_USERNAME` / `AUTH_PASSWORD`；或使用部署时的默认 `admin` / `admin123` 后在设置中修改。
+
+**Q：添加成功但查询不到？**  
+A：确认查询的类型与添加时一致；交易所需选对 Binance/OKX/Gate。
+
+**Q：局域网手机打不开？**  
+A：确认手机与服务器同一 WiFi；防火墙放行 5200；使用 `http://服务器IP:5200` 而非 127.0.0.1。
+
+**Q：复制按钮无效？**  
+A：使用 `http://` 访问（非 `file://`）；浏览器需允许剪贴板权限。
+
+**Q：更新代码后无法登录或数据打不开？**  
+A：执行 `pip install -r requirements.txt` 并重启 PM2；确认 `.env` 中 `DATA_ENCRYPTION_KEY` 未变。
+
+**Q：旧版明文 data.json 还能用吗？**  
+A：可以。服务启动后首次读取会自动迁移为加密格式，建议迁移前备份原文件。
+
+---
+
+## 9. 相关文档
+
+| 文档 | 内容 |
+|------|------|
+| [README.md](./README.md) | 项目概览 |
+| [DEPLOY.md](./DEPLOY.md) | 安装与运维 |
+| [CHANGELOG.md](./CHANGELOG.md) | 版本更新记录 |