ViGent2/Docs/AUTH_DEPLOY.md

用户认证系统部署指南

📋 概述

本文档描述如何在 Ubuntu 服务器上部署 ViGent2 用户认证系统。

组件	技术	说明
数据库	Supabase (PostgreSQL)	云端免费版
认证	FastAPI + JWT	HttpOnly Cookie
密码	bcrypt	单向哈希

---

步骤 1: 配置 Supabase

1.1 创建项目

1. 访问 supabase.com
2. 创建免费项目
3. 记录以下信息：
   • Project URL: https://xxx.supabase.co
   • anon public key: eyJhbGciOiJIUzI1NiIs...

1.2 创建数据库表

1. 进入 SQL Editor
2. 执行以下 SQL：

-- 1. 创建 users 表
CREATE TABLE IF NOT EXISTS users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email TEXT UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    username TEXT,
    role TEXT DEFAULT 'pending' CHECK (role IN ('pending', 'user', 'admin')),
    is_active BOOLEAN DEFAULT FALSE,
    expires_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 2. 创建 user_sessions 表
CREATE TABLE IF NOT EXISTS user_sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE UNIQUE,
    session_token TEXT UNIQUE NOT NULL,
    device_info TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 3. 创建 social_accounts 表
CREATE TABLE IF NOT EXISTS social_accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    platform TEXT NOT NULL CHECK (platform IN ('bilibili', 'douyin', 'xiaohongshu')),
    logged_in BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(user_id, platform)
);

-- 4. 创建索引
CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON user_sessions(user_id);
CREATE INDEX IF NOT EXISTS idx_social_user_platform ON social_accounts(user_id, platform);

---

步骤 2: 配置后端环境变量

编辑 /home/rongye/ProgramFiles/ViGent2/backend/.env：

# =============== Supabase 配置 ===============
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIs...

# =============== JWT 配置 ===============
JWT_SECRET_KEY=随机生成的32位以上字符串
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=168  # 7天

# =============== 管理员配置 ===============
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=YourSecurePassword123!

生成 JWT 密钥

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

---

步骤 3: 安装依赖

cd /home/rongye/ProgramFiles/ViGent2/backend
source venv/bin/activate

pip install supabase python-jose[cryptography] passlib[bcrypt]

---

步骤 4: 启动服务

# 重启后端服务
pm2 restart vigent2-backend

首次启动时，管理员账号会自动创建。查看日志确认：

pm2 logs vigent2-backend | grep "管理员"

应该看到：管理员账号已创建: admin@example.com

---

步骤 5: 验证

API 测试

# 健康检查
curl http://localhost:8006/health

# 注册测试
curl -X POST http://localhost:8006/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"123456"}'

# 登录测试 (管理员)
curl -X POST http://localhost:8006/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"YourSecurePassword123!"}'

---

步骤 6: 防止 Supabase 7 天暂停

Supabase 免费版 7 天无活动会暂停。推荐使用服务器 crontab 方案。

方案 A: 服务器 crontab（推荐）

在 Ubuntu 服务器上执行：

crontab -e

添加以下行（每天凌晨 1 点执行）：

0 1 * * * curl -s -X GET "https://zcmitzlqlyzxlgwagouf.supabase.co/rest/v1/" -H "apikey: YOUR_SUPABASE_ANON_KEY" > /dev/null

将 YOUR_SUPABASE_ANON_KEY 替换为实际的 anon key

方案 B: GitHub Actions

如果服务器可能长期关闭，可使用 GitHub Actions。

1. 创建独立仓库：supabase-keep-alive
2. 上传 .github/workflows/keep-supabase-alive.yml
3. 配置 Secrets：SUPABASE_URL, SUPABASE_KEY

⚠️ 需要 GitHub 账户有付款信息（免费计划也需要）

---

📁 文件结构

backend/
├── app/
│   ├── api/
│   │   ├── auth.py         # 注册/登录/登出
│   │   └── admin.py        # 用户管理
│   └── core/
│       ├── supabase.py     # Supabase 客户端
│       ├── security.py     # JWT + 密码
│       ├── paths.py        # Cookie 路径隔离
│       └── deps.py         # 认证依赖
├── database/
│   └── schema.sql          # 数据库表定义
└── user_data/              # 用户 Cookie (按 user_id 隔离)
    └── {user-uuid}/
        └── cookies/

---

🔑 用户管理

在 Supabase Dashboard 中管理

1. 进入 Table Editor > users
2. 激活用户：设置 is_active = true, role = user
3. 设置过期时间：填写 expires_at 字段

使用 API 管理

需要管理员 Cookie：

# 获取用户列表
curl http://localhost:8006/api/admin/users -b "access_token=..."

# 激活用户 (30天有效期)
curl -X POST http://localhost:8006/api/admin/users/{user_id}/activate \
  -H "Content-Type: application/json" \
  -b "access_token=..." \
  -d '{"expires_days": 30}'