zjpb.net/DEPLOY_v3.0.md

# ZJPB v3.0 服务端部署指南

**版本：** v3.0.1 (已修复5个代码问题)
**部署日期：** 2025-02-06
**重要程度：** 🔴 重大更新（需要数据库迁移）

---

## 🆕 v3.0.1 更新说明

**最新提交：** 7a6fd0c

已修复以下问题：
1. ✅ Collection 模型唯一约束逻辑错误
2. ✅ 用户注册重复提交数据库
3. ✅ JavaScript 未使用的变量
4. ✅ 文件夹计数逻辑缺失
5. ✅ JavaScript 错误处理不完善

详细修复记录请查看：`BUGFIX_v3.0.1.md`

---

## 📋 部署前准备

### 1. 系统要求

- Python 3.8+
- MySQL/MariaDB 数据库
- Git
- 足够的磁盘空间（建议至少 1GB）

### 2. 备份现有数据

**⚠️ 重要：在部署前务必备份数据库！**

```bash
# 备份数据库
mysqldump -u root -p zjpb > zjpb_backup_$(date +%Y%m%d_%H%M%S).sql

# 或者如果使用 SQLite
cp instance/zjpb.db instance/zjpb_backup_$(date +%Y%m%d_%H%M%S).db
```

---

## 🚀 部署步骤

### 步骤 1：登录服务器

```bash
ssh your_username@server.zjpb.net
```

### 步骤 2：进入项目目录

```bash
cd /opt/1panel/apps/zjpb
```

### 步骤 3：拉取最新代码

```bash
# 查看当前分支
git branch

# 拉取最新代码
git pull origin master
```

**预期输出：**
```
remote: Enumerating objects: 15, done.
remote: Counting objects: 100% (15/15), done.
...
Updating 34cd05b..2067fb1
Fast-forward
 11 files changed, 2542 insertions(+), 6 deletions(-)
 create mode 100644 CHANGELOG_v3.0.md
 create mode 100644 USER_SYSTEM_README.md
 ...
```

### 步骤 4：激活虚拟环境

```bash
# 如果使用 virtualenv
source venv/bin/activate

# 或者如果使用 conda
conda activate zjpb
```

### 步骤 5：安装/更新依赖

```bash
# 检查是否有新的依赖（v3.0 没有新增依赖）
pip install -r requirements.txt
```

### 步骤 6：运行数据库迁移 ⭐

**这是最关键的一步！**

```bash
python create_user_tables.py
```

**预期输出：**
```
开始创建用户系统表...
SUCCESS: Database tables created successfully!

Created tables:
- users
- folders
- collections

Migration completed!
```

**如果出现错误：**
- 检查数据库连接配置
- 确认数据库用户有 CREATE TABLE 权限
- 查看错误信息并根据提示修复

**⚠️ 如果之前已运行过 v3.0.0（未修复版本）：**

需要运行约束修复脚本：
```bash
python fix_collection_constraint.py
```

这将修复 Collection 表的唯一约束问题。

### 步骤 7：验证数据库表

```bash
# 进入数据库
mysql -u root -p zjpb

# 或者使用 Python 验证
python -c "from app import create_app; from models import db, User, Folder, Collection; app = create_app(); app.app_context().push(); print('Users table:', db.engine.has_table('users')); print('Folders table:', db.engine.has_table('folders')); print('Collections table:', db.engine.has_table('collections'))"
```

**预期输出：**
```
Users table: True
Folders table: True
Collections table: True
```

### 步骤 8：重启应用服务

根据您的部署方式选择对应的重启命令：

**如果使用 Systemd：**
```bash
sudo systemctl restart zjpb
sudo systemctl status zjpb
```

**如果使用 Supervisor：**
```bash
sudo supervisorctl restart zjpb
sudo supervisorctl status zjpb
```

**如果使用 PM2：**
```bash
pm2 restart zjpb
pm2 status
```

**如果使用 Gunicorn 手动启动：**
```bash
# 先停止旧进程
pkill -f gunicorn

# 启动新进程
gunicorn -w 4 -b 0.0.0.0:5000 app:app --daemon
```

### 步骤 9：验证部署成功

```bash
# 检查应用是否正常运行
curl http://localhost:5000/

# 检查新增的路由
curl http://localhost:5000/register
curl http://localhost:5000/login
```

---

## ✅ 功能测试清单

部署完成后，请按以下步骤测试所有功能：

### 1. 用户注册测试

1. 访问 `https://your-domain.com/register`
2. 输入用户名（至少3个字符）
3. 输入密码（至少6个字符）
4. 确认密码
5. 点击"注册"按钮
6. ✅ 应该自动登录并跳转到首页
7. ✅ 导航栏右上角应显示用户名

### 2. 用户登录测试

1. 点击导航栏的"退出登录"
2. 访问 `https://your-domain.com/login`
3. 输入刚才注册的用户名和密码
4. 点击"登录"按钮
5. ✅ 应该跳转到首页并显示登录状态

### 3. 收藏功能测试

1. 登录后访问任意工具详情页
2. 找到"收藏"按钮（在"访问网站"按钮下方）
3. 点击"收藏"按钮
4. ✅ 按钮应变为金色并显示"已收藏"
5. ✅ 页面顶部应显示"收藏成功"提示
6. 再次点击按钮
7. ✅ 应取消收藏并恢复原状

### 4. 用户中心测试

1. 点击导航栏的用户头像/用户名
2. 选择"个人中心"
3. ✅ 应显示用户信息和统计数据
4. ✅ 收藏数应该正确显示
5. ✅ 最近收藏列表应显示刚才收藏的工具

### 5. 收藏列表测试

1. 在用户中心点击"我的收藏"
2. 或访问 `https://your-domain.com/user/collections`
3. ✅ 应显示所有收藏的工具
4. ✅ 文件夹标签应正常显示
5. ✅ 点击工具卡片应跳转到详情页

### 6. 权限隔离测试 ⚠️

**测试普通用户无法访问管理后台：**

1. 使用普通用户账号登录
2. 尝试访问 `https://your-domain.com/admin/`
3. ✅ 应该被拒绝访问（403错误或跳转）
4. 尝试访问 `https://your-domain.com/admin/seo-tools`
5. ✅ 应该被拒绝访问

**测试管理员登录：**

1. 退出普通用户账号
2. 访问 `https://your-domain.com/admin/login`
3. 使用管理员账号登录
4. ✅ 应该能正常访问管理后台

---

## 🔧 故障排查

### 问题 1：数据库迁移失败

**错误信息：**
```
ERROR: Failed to create tables: (pymysql.err.OperationalError) ...
```

**解决方案：**
```bash
# 1. 检查数据库连接
python -c "from app import create_app; app = create_app(); print('Database URI:', app.config['SQLALCHEMY_DATABASE_URI'])"

# 2. 检查数据库用户权限
mysql -u root -p
GRANT ALL PRIVILEGES ON zjpb.* TO 'your_db_user'@'localhost';
FLUSH PRIVILEGES;

# 3. 重新运行迁移
python create_user_tables.py
```

### 问题 2：应用启动失败

**错误信息：**
```
ImportError: cannot import name 'User' from 'models'
```

**解决方案：**
```bash
# 1. 确认代码已正确拉取
git log -1 --oneline
# 应该显示：2067fb1 feat: v3.0 - 用户系统和收藏功能

# 2. 重新安装依赖
pip install -r requirements.txt --force-reinstall

# 3. 清除 Python 缓存
find . -type d -name __pycache__ -exec rm -r {} +
find . -type f -name "*.pyc" -delete
```

### 问题 3：收藏按钮不显示

**可能原因：**
- 静态文件缓存
- JavaScript 加载失败

**解决方案：**
```bash
# 1. 清除浏览器缓存（Ctrl + Shift + Delete）

# 2. 检查模板文件是否正确更新
grep -n "collectBtn" templates/detail_new.html

# 3. 强制刷新页面（Ctrl + F5）
```

### 问题 4：管理员需要重新登录

**这是正常现象！**

由于 v3.0 修改了 `Admin.get_id()` 的返回格式（从 `id` 改为 `admin:id`），所有管理员需要重新登录一次。

**解决步骤：**
1. 访问 `/admin/login`
2. 使用管理员账号重新登录
3. 之后就可以正常使用了

### 问题 5：普通用户仍能访问管理后台

**这是严重的安全问题！**

**检查步骤：**
```bash
# 1. 确认代码版本
git log -1 --grep="v3.0"

# 2. 检查 app.py 中的权限检查
grep -A 3 "isinstance(current_user, AdminModel)" app.py | head -20

# 3. 重启应用
sudo systemctl restart zjpb
```

---

## 📊 性能优化建议

### 1. 数据库索引验证

```sql
-- 进入数据库
mysql -u root -p zjpb

-- 检查索引
SHOW INDEX FROM users;
SHOW INDEX FROM folders;
SHOW INDEX FROM collections;
```

**应该看到以下索引：**
- users: username, email
- folders: user_id, public_slug
- collections: user_id, site_id, folder_id, (user_id, folder_id)

### 2. 静态文件缓存

如果使用 Nginx，建议添加静态文件缓存：

```nginx
location /static/ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}
```

### 3. 数据库连接池

检查 `app.py` 中的数据库配置：

```python
SQLALCHEMY_POOL_SIZE = 10
SQLALCHEMY_POOL_RECYCLE = 3600
SQLALCHEMY_MAX_OVERFLOW = 20
```

---

## 🔐 安全检查清单

部署后请确认以下安全措施：

- [ ] 普通用户无法访问 `/admin/` 路径
- [ ] 普通用户无法访问管理员 API 端点
- [ ] 管理员无法使用收藏功能（这是设计行为）
- [ ] 密码已正确哈希存储（不是明文）
- [ ] HTTPS 已启用（生产环境必须）
- [ ] 数据库备份已完成

---

## 📝 部署记录模板

建议在部署后记录以下信息：

```
部署日期：2025-02-06
部署版本：v3.0.0
部署人员：[您的名字]
服务器：server.zjpb.net
数据库迁移：✅ 成功
应用重启：✅ 成功
功能测试：✅ 通过
权限测试：✅ 通过

备注：
- 数据库备份文件：zjpb_backup_20250206_HHMMSS.sql
- 管理员已重新登录
- 所有功能测试通过
```

---

## 🎯 后续维护建议

### 1. 监控用户注册

```bash
# 查看用户数量
mysql -u root -p zjpb -e "SELECT COUNT(*) as user_count FROM users;"

# 查看最近注册的用户
mysql -u root -p zjpb -e "SELECT id, username, created_at FROM users ORDER BY created_at DESC LIMIT 10;"
```

### 2. 监控收藏数据

```bash
# 查看收藏总数
mysql -u root -p zjpb -e "SELECT COUNT(*) as collection_count FROM collections;"

# 查看最活跃的用户
mysql -u root -p zjpb -e "SELECT user_id, COUNT(*) as count FROM collections GROUP BY user_id ORDER BY count DESC LIMIT 10;"
```

### 3. 定期备份

建议设置定时任务自动备份：

```bash
# 编辑 crontab
crontab -e

# 添加每天凌晨3点备份
0 3 * * * mysqldump -u root -p'your_password' zjpb > /backup/zjpb_$(date +\%Y\%m\%d).sql
```

### 4. 日志监控

```bash
# 查看应用日志
tail -f /var/log/zjpb/app.log

# 或者如果使用 systemd
journalctl -u zjpb -f
```

---

## 📞 技术支持

如遇到问题，请查看：

1. **用户系统文档**：`USER_SYSTEM_README.md`
2. **版本更新日志**：`CHANGELOG_v3.0.md`
3. **Flask-Login 文档**：https://flask-login.readthedocs.io/
4. **SQLAlchemy 文档**：https://docs.sqlalchemy.org/

---

## ✅ 部署完成确认

当您完成以上所有步骤后，请确认：

- ✅ 代码已成功拉取（commit: 2067fb1）
- ✅ 数据库表已创建（users, folders, collections）
- ✅ 应用已重启并正常运行
- ✅ 用户注册功能正常
- ✅ 用户登录功能正常
- ✅ 收藏功能正常
- ✅ 用户中心正常显示
- ✅ 权限隔离正常（普通用户无法访问管理后台）
- ✅ 管理员已重新登录

**恭喜！v3.0 部署成功！** 🎉

---

**文档版本：** v1.0
**最后更新：** 2025-02-06
**作者：** Claude Sonnet 4.5