463 lines
11 KiB
Markdown
463 lines
11 KiB
Markdown
# Supabase 消息系统部署清单
|
||
|
||
本清单确保您在Supabase中正确配置消息系统的权限策略和功能。
|
||
|
||
## 🎯 部署选项
|
||
|
||
### 选项1：一键部署（推荐新手）
|
||
|
||
```sql
|
||
-- 在Supabase SQL编辑器中执行
|
||
\i deploy_one_click.sql
|
||
```
|
||
|
||
**优点：**
|
||
- ✅ 自动化程度高，一步完成
|
||
- ✅ 包含环境检测和配置验证
|
||
- ✅ 自动创建便捷开发函数
|
||
- ✅ 生成详细的部署报告
|
||
|
||
**包含内容：**
|
||
- 数据库扩展检查与创建
|
||
- 基础表结构创建
|
||
- 开发权限模式部署
|
||
- 基础消息类型数据
|
||
- 便捷开发函数
|
||
- 部署结果验证
|
||
|
||
### 选项2：权限管理器模式
|
||
|
||
```sql
|
||
-- 1. 部署权限管理器
|
||
\i permission_manager.sql
|
||
|
||
-- 2. 查看当前状态
|
||
SELECT * FROM public.permission_dashboard;
|
||
|
||
-- 3. 智能切换权限模式
|
||
SELECT public.switch_to_dev_mode(); -- 开发模式
|
||
SELECT public.switch_to_prod_mode(); -- 生产模式
|
||
|
||
-- 4. 健康检查
|
||
SELECT * FROM public.check_permission_health();
|
||
```
|
||
|
||
**优点：**
|
||
- 🎛️ 提供完整的权限管理界面
|
||
- 🔄 支持权限模式智能切换
|
||
- 📊 实时权限状态监控
|
||
- 🔍 权限健康检查和诊断
|
||
|
||
### 选项3：手动分步部署
|
||
|
||
```sql
|
||
-- 1. 基础表结构
|
||
\i message_system.sql
|
||
|
||
-- 2. 用户角色系统（生产环境）
|
||
\i supabase_auth_complete_setup.sql
|
||
|
||
-- 3. 权限策略
|
||
-- 开发环境
|
||
\i dev_open_permissions.sql
|
||
-- 或生产环境
|
||
\i message_permissions_complete.sql
|
||
|
||
-- 4. 测试数据
|
||
\i insert_test_message_data.sql
|
||
```
|
||
|
||
**优点：**
|
||
- 🎯 精确控制每个部署步骤
|
||
- 🛠️ 便于调试和故障排除
|
||
- 📝 适合学习和理解系统架构
|
||
- 🔧 支持自定义配置
|
||
|
||
## 🔄 权限模式管理
|
||
|
||
### 权限模式脚本列表
|
||
|
||
| 脚本文件 | 用途 | 适用环境 |
|
||
|----------|------|----------|
|
||
| `open_all_message_permissions.sql` | 完整开放权限脚本 | 开发/测试 |
|
||
| `dev_open_permissions.sql` | 快速开发权限脚本 | 开发/测试 |
|
||
| `restore_normal_permissions.sql` | 恢复正常权限脚本 | 生产环境 |
|
||
| `permission_manager.sql` | 权限管理器 | 所有环境 |
|
||
|
||
### 开发模式设置
|
||
|
||
**快速开启开发模式：**
|
||
```sql
|
||
-- 方法1：使用完整脚本
|
||
\i open_all_message_permissions.sql
|
||
|
||
-- 方法2：使用快速脚本
|
||
\i dev_open_permissions.sql
|
||
|
||
-- 方法3：使用管理函数
|
||
SELECT public.switch_to_dev_mode();
|
||
```
|
||
|
||
**开发模式特点：**
|
||
- ✅ 所有authenticated用户拥有完全权限
|
||
- ✅ 提供便捷开发函数
|
||
- ✅ 适合快速原型开发和测试
|
||
- ⚠️ **严禁在生产环境使用**
|
||
|
||
### 生产模式设置
|
||
|
||
**恢复生产模式：**
|
||
```sql
|
||
-- 方法1：使用恢复脚本
|
||
\i restore_normal_permissions.sql
|
||
|
||
-- 方法2：使用管理函数（仅清理）
|
||
SELECT public.switch_to_prod_mode();
|
||
-- 然后手动运行完整的生产权限脚本
|
||
|
||
-- 方法3：重新部署完整权限
|
||
\i message_permissions_complete.sql
|
||
```
|
||
|
||
**生产模式特点：**
|
||
- 🔒 基于角色的严格权限控制
|
||
- 🎯 最小权限原则
|
||
- 🛡️ 数据安全保护
|
||
- ✅ 适合生产环境
|
||
|
||
### 权限状态检查
|
||
|
||
**查看当前权限模式：**
|
||
```sql
|
||
-- 查看权限模式
|
||
SELECT * FROM public.get_permission_mode();
|
||
|
||
-- 查看权限仪表板
|
||
SELECT * FROM public.permission_dashboard;
|
||
|
||
-- 详细策略列表
|
||
SELECT * FROM public.list_message_policies();
|
||
|
||
-- 权限健康检查
|
||
SELECT * FROM public.check_permission_health();
|
||
```
|
||
|
||
**常用检查命令：**
|
||
```sql
|
||
-- 快速状态检查
|
||
SELECT
|
||
mode,
|
||
CASE
|
||
WHEN dev_policies > 0 THEN '⚠️ 开发环境'
|
||
WHEN normal_policies > 0 THEN '✅ 生产环境'
|
||
ELSE '❌ 未配置'
|
||
END as status
|
||
FROM public.get_permission_mode();
|
||
```
|
||
|
||
## 🏗️ 数据库架构部署
|
||
|
||
### 1. 创建表结构
|
||
```sql
|
||
-- 首先执行主数据库架构
|
||
\i message_system.sql
|
||
|
||
-- 然后执行权限策略
|
||
\i supabase_message_permissions.sql
|
||
|
||
-- 最后插入测试数据
|
||
\i insert_test_message_data.sql
|
||
```
|
||
|
||
### 2. 启用必要的扩展
|
||
```sql
|
||
-- 在 Supabase SQL Editor 中执行
|
||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||
CREATE EXTENSION IF NOT EXISTS "pg_trgm"; -- 用于文本搜索
|
||
```
|
||
|
||
## 🔐 认证和权限配置
|
||
|
||
### 1. JWT 配置
|
||
确保您的 Supabase JWT 包含用户角色信息：
|
||
|
||
```json
|
||
{
|
||
"aud": "authenticated",
|
||
"exp": 1234567890,
|
||
"sub": "user-uuid-here",
|
||
"email": "user@example.com",
|
||
"role": "authenticated",
|
||
"user_role": "teacher", // 重要：自定义角色字段
|
||
"app_metadata": {
|
||
"provider": "email",
|
||
"providers": ["email"]
|
||
},
|
||
"user_metadata": {
|
||
"user_role": "teacher" // 备用角色字段
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 用户表配置
|
||
确保用户表包含角色信息：
|
||
|
||
```sql
|
||
-- 检查用户表结构
|
||
SELECT column_name, data_type, is_nullable
|
||
FROM information_schema.columns
|
||
WHERE table_name = 'ak_users' AND table_schema = 'public';
|
||
|
||
-- 添加角色列到用户表（如果还没有）
|
||
ALTER TABLE public.ak_users
|
||
ADD COLUMN IF NOT EXISTS role VARCHAR(20) DEFAULT 'student',
|
||
ADD COLUMN IF NOT EXISTS user_type VARCHAR(20) DEFAULT 'student',
|
||
ADD COLUMN IF NOT EXISTS class_id UUID; -- 用于班级关联
|
||
|
||
-- 更新测试用户角色
|
||
UPDATE public.ak_users
|
||
SET role = 'teacher', user_type = 'teacher'
|
||
WHERE id = '7bf7378e-a027-473e-97ac-3460ed3f170a';
|
||
|
||
UPDATE public.ak_users
|
||
SET role = 'student', user_type = 'student'
|
||
WHERE id = 'eed3824b-bba1-4309-8048-19d17367c084';
|
||
|
||
-- 如果需要，可以创建班级表和师生关系
|
||
-- CREATE TABLE IF NOT EXISTS public.ak_classes (
|
||
-- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
-- name VARCHAR(100) NOT NULL,
|
||
-- description TEXT,
|
||
-- teacher_id UUID REFERENCES public.ak_users(id),
|
||
-- created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||
-- );
|
||
```
|
||
|
||
## 📊 实时订阅配置
|
||
|
||
### 1. 在 Supabase 控制台中启用实时功能
|
||
|
||
**Database → Replication**
|
||
- 选择需要实时订阅的表：
|
||
- ✅ `ak_messages`
|
||
- ✅ `ak_message_recipients`
|
||
- ✅ `ak_message_groups`
|
||
- ✅ `ak_message_group_members`
|
||
|
||
### 2. 实时策略配置
|
||
```sql
|
||
-- 允许用户订阅自己的消息更新
|
||
ALTER PUBLICATION supabase_realtime ADD TABLE public.ak_messages;
|
||
ALTER PUBLICATION supabase_realtime ADD TABLE public.ak_message_recipients;
|
||
ALTER PUBLICATION supabase_realtime ADD TABLE public.ak_message_groups;
|
||
ALTER PUBLICATION supabase_realtime ADD TABLE public.ak_message_group_members;
|
||
```
|
||
|
||
## 🔧 客户端环境变量
|
||
|
||
创建 `.env.local` 文件：
|
||
```env
|
||
NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
|
||
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
|
||
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key # 仅服务端使用
|
||
```
|
||
|
||
## 🧪 权限策略测试
|
||
|
||
### 1. 基本权限测试
|
||
|
||
在 Supabase SQL Editor 中执行：
|
||
|
||
```sql
|
||
-- 测试用户只能查看自己的消息
|
||
SET LOCAL role = 'authenticated';
|
||
SET LOCAL "request.jwt.claims" = '{"sub": "eed3824b-bba1-4309-8048-19d17367c084", "user_role": "student"}';
|
||
|
||
-- 应该只返回学生相关的消息
|
||
SELECT COUNT(*) FROM ak_messages;
|
||
SELECT COUNT(*) FROM ak_message_recipients WHERE recipient_id = 'eed3824b-bba1-4309-8048-19d17367c084'::uuid;
|
||
|
||
-- 重置
|
||
RESET role;
|
||
```
|
||
|
||
### 2. 教师权限测试
|
||
|
||
```sql
|
||
-- 设置教师身份
|
||
SET LOCAL role = 'authenticated';
|
||
SET LOCAL "request.jwt.claims" = '{"sub": "7bf7378e-a027-473e-97ac-3460ed3f170a", "user_role": "teacher"}';
|
||
|
||
-- 测试教师可以发送系统消息
|
||
INSERT INTO ak_messages (
|
||
message_type_id,
|
||
sender_type,
|
||
sender_id,
|
||
receiver_type,
|
||
receiver_id,
|
||
title,
|
||
content
|
||
) VALUES (
|
||
(SELECT id FROM ak_message_types WHERE code = 'assignment'),
|
||
'user',
|
||
'7bf7378e-a027-473e-97ac-3460ed3f170a',
|
||
'user',
|
||
'eed3824b-bba1-4309-8048-19d17367c084',
|
||
'权限测试消息',
|
||
'这是一条测试教师权限的消息'
|
||
);
|
||
|
||
-- 重置
|
||
RESET role;
|
||
```
|
||
|
||
### 3. 群组权限测试
|
||
|
||
```sql
|
||
-- 测试群组成员权限
|
||
SET LOCAL role = 'authenticated';
|
||
SET LOCAL "request.jwt.claims" = '{"sub": "eed3824b-bba1-4309-8048-19d17367c084", "user_role": "student"}';
|
||
|
||
-- 学生应该能看到自己参与的群组
|
||
SELECT * FROM ak_message_groups;
|
||
|
||
-- 重置
|
||
RESET role;
|
||
```
|
||
|
||
## 📱 前端集成检查清单
|
||
|
||
### 1. 认证流程
|
||
- [ ] 用户登录后正确设置角色信息
|
||
- [ ] JWT 包含 `user_role` 字段
|
||
- [ ] 角色信息在用户会话中持久化
|
||
|
||
### 2. 消息功能
|
||
- [ ] 用户只能看到自己有权限的消息
|
||
- [ ] 教师可以向学生发送消息
|
||
- [ ] 学生可以标记消息为已读
|
||
- [ ] 群组消息正常工作
|
||
|
||
### 3. 实时功能
|
||
- [ ] 新消息实时推送给正确的用户
|
||
- [ ] 消息状态变化实时同步
|
||
- [ ] 订阅自动受权限策略保护
|
||
|
||
### 4. 错误处理
|
||
- [ ] 权限不足时显示友好错误信息
|
||
- [ ] 网络错误重试机制
|
||
- [ ] 操作失败回滚机制
|
||
|
||
## 🚀 生产环境部署
|
||
|
||
### 1. 性能优化
|
||
|
||
```sql
|
||
-- 创建必要的索引
|
||
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_messages_recipient_user
|
||
ON ak_message_recipients (recipient_id, recipient_type)
|
||
WHERE recipient_type = 'user';
|
||
|
||
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_messages_sender_user
|
||
ON ak_messages (sender_id, sender_type)
|
||
WHERE sender_type = 'user';
|
||
|
||
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_messages_created_at_desc
|
||
ON ak_messages (created_at DESC);
|
||
|
||
-- 分析表统计信息
|
||
ANALYZE ak_messages;
|
||
ANALYZE ak_message_recipients;
|
||
ANALYZE ak_message_groups;
|
||
```
|
||
|
||
### 2. 监控和日志
|
||
|
||
在 Supabase 控制台中：
|
||
- **Logs** → 查看数据库日志
|
||
- **API** → 监控 API 使用情况
|
||
- **Auth** → 监控认证失败
|
||
|
||
### 3. 备份策略
|
||
|
||
```sql
|
||
-- 定期备份重要数据
|
||
pg_dump -h your-db-host -U postgres -d your-db-name \
|
||
--table=ak_messages \
|
||
--table=ak_message_recipients \
|
||
--table=ak_message_groups \
|
||
--table=ak_user_message_preferences \
|
||
> message_system_backup.sql
|
||
```
|
||
|
||
## 🔒 安全检查清单
|
||
|
||
### 1. 权限策略审查
|
||
- [ ] 所有表都启用了 RLS
|
||
- [ ] 用户只能访问自己的数据
|
||
- [ ] 敏感操作需要适当权限
|
||
- [ ] 没有权限泄露或越权访问
|
||
|
||
### 2. 数据验证
|
||
- [ ] 输入数据经过验证和清理
|
||
- [ ] 防止 SQL 注入攻击
|
||
- [ ] 文件上传安全检查
|
||
- [ ] 敏感信息加密存储
|
||
|
||
### 3. 网络安全
|
||
- [ ] 启用 HTTPS
|
||
- [ ] 配置 CORS 策略
|
||
- [ ] API 速率限制
|
||
- [ ] 防止暴力破解
|
||
|
||
## 📞 故障排查
|
||
|
||
### 常见问题和解决方案
|
||
|
||
**问题1：权限被拒绝错误**
|
||
```
|
||
解决方案：
|
||
1. 检查用户是否已认证
|
||
2. 验证 JWT 中的角色信息
|
||
3. 确认 RLS 策略配置正确
|
||
4. 检查表权限设置
|
||
```
|
||
|
||
**问题2：实时订阅不工作**
|
||
```
|
||
解决方案：
|
||
1. 确认表已添加到实时发布
|
||
2. 检查 RLS 策略是否阻止订阅
|
||
3. 验证客户端连接状态
|
||
4. 查看浏览器开发者工具错误
|
||
```
|
||
|
||
**问题3：消息发送失败**
|
||
```
|
||
解决方案：
|
||
1. 检查消息类型是否存在
|
||
2. 验证接收者ID有效性
|
||
3. 确认发送者有权限发送该类型消息
|
||
4. 检查函数参数类型匹配
|
||
```
|
||
|
||
## 📈 性能监控
|
||
|
||
### 关键指标
|
||
- 消息发送延迟
|
||
- 数据库查询时间
|
||
- 实时连接数量
|
||
- 错误率统计
|
||
|
||
### 优化建议
|
||
1. 定期分析慢查询
|
||
2. 监控索引使用情况
|
||
3. 优化复杂权限策略
|
||
4. 考虑数据分区策略
|
||
|
||
---
|
||
|
||
**完成部署后，使用提供的测试用户 ID 进行功能验证：**
|
||
- 教师：`7bf7378e-a027-473e-97ac-3460ed3f170a`
|
||
- 学生：`eed3824b-bba1-4309-8048-19d17367c084`
|