docs: 完善成人内容过滤功能文档和配置

文档更新:
- 更新README中成人内容过滤部分,添加Cloudflare Pages配置要求
- 新增CLOUDFLARE_PAGES_ADULT_FILTER.md详细配置指南
- 更新D1_MIGRATION.md,修正user_settings表结构

 数据库优化:
- 修复scripts/d1-init.sql,添加缺失的user_settings表
- 更新表结构以匹配当前实现
- 添加必要的索引优化查询性能

 问题修复:
- 解决Cloudflare Pages部署时'获取用户设置失败'错误
- 明确说明不同部署平台的存储类型要求
- 提供详细的故障排除指南
This commit is contained in:
katelya
2025-09-04 22:55:28 +08:00
parent ff388a8085
commit db08179eb0
4 changed files with 384 additions and 41 deletions
+194
View File
@@ -0,0 +1,194 @@
# Cloudflare Pages 成人内容过滤配置指南
本文档详细说明如何在 Cloudflare Pages 部署中配置成人内容过滤功能。
## ⚠️ 重要说明
成人内容过滤功能需要**数据库存储支持**,不能使用默认的 `localstorage` 存储类型。在 Cloudflare Pages 环境下,必须配置 D1 数据库。
## 🚀 快速配置步骤
### 1. 创建 D1 数据库
```bash
# 安装并登录 Wrangler CLI
npm install -g wrangler
wrangler auth login
# 创建 D1 数据库
wrangler d1 create katelyatv-db
```
记录输出的数据库 ID,类似:
```
✅ Successfully created DB 'katelyatv-db' in region APAC
Created your database using D1's new storage backend.
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```
### 2. 初始化数据库表
```bash
# 克隆项目(如果还没有)
git clone https://github.com/your-username/KatelyaTV.git
cd KatelyaTV
# 初始化数据库表(包含 user_settings 表)
wrangler d1 execute katelyatv-db --file=./scripts/d1-init.sql
```
### 3. 配置 wrangler.toml
在项目根目录创建或更新 `wrangler.toml` 文件:
```toml
name = "katelyatv"
compatibility_date = "2023-12-01"
compatibility_flags = ["nodejs_compat"]
[[d1_databases]]
binding = "DB"
database_name = "katelyatv-db"
database_id = "your-database-id-here" # 替换为步骤1中获得的ID
[build]
command = "pnpm install --frozen-lockfile && pnpm run pages:build"
[[build.environment_variables]]
NEXT_PUBLIC_STORAGE_TYPE = "d1"
[vars]
USERNAME = "admin"
PASSWORD = "your_password_here"
NEXT_PUBLIC_ENABLE_REGISTER = "true"
```
### 4. 部署到 Cloudflare Pages
#### 方法一:通过 Cloudflare Dashboard
1. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com/)
2. 进入 **Pages** 服务
3. 点击 **Create a project**
4. 连接 GitHub 仓库并选择 KatelyaTV 项目
5. 配置构建设置:
- **Build command**: `pnpm install --frozen-lockfile && pnpm run pages:build`
- **Build output directory**: `.vercel/output/static`
- **Root directory**: 留空
6.**Environment variables** 中添加:
```
NEXT_PUBLIC_STORAGE_TYPE = d1
USERNAME = admin
PASSWORD = your_password_here
NEXT_PUBLIC_ENABLE_REGISTER = true
```
7. 在 **Functions** 标签页中:
- 启用 **Compatibility flags**: `nodejs_compat`
- 配置 **D1 database bindings**:
- Variable name: `DB`
- D1 database: 选择刚创建的数据库
#### 方法二:通过命令行部署
```bash
# 构建项目
pnpm install --frozen-lockfile
pnpm run pages:build
# 部署到 Pages
wrangler pages deploy .vercel/output/static --project-name katelyatv
```
## 🔍 验证配置
部署完成后,访问你的网站:
1. **登录系统**:使用配置的用户名密码登录
2. **访问设置页面**:点击用户菜单中的「内容过滤」
3. **检查功能**:应该能够看到成人内容过滤开关,而不是"获取用户设置失败"错误
## 🐛 故障排除
### 错误:"获取用户设置失败"
**可能原因**
- 未配置 D1 数据库
- `NEXT_PUBLIC_STORAGE_TYPE` 未设置为 `d1`
- 数据库中缺少 `user_settings` 表
**解决方案**
1. 检查环境变量配置
2. 验证 D1 数据库绑定
3. 执行数据库迁移:
```bash
wrangler d1 execute katelyatv-db --file=./scripts/d1-init.sql
```
### 错误:D1 数据库连接失败
**可能原因**
- wrangler.toml 中的数据库配置错误
- Cloudflare Pages 中的 D1 绑定未正确配置
**解决方案**
1. 验证 `wrangler.toml` 中的 database_id 是否正确
2. 在 Cloudflare Pages Dashboard 中检查 Functions → D1 database bindings
3. 确保绑定的变量名为 `DB`
### 错误:构建失败
**可能原因**
- Node.js 兼容性问题
- 依赖安装失败
**解决方案**
1. 确保启用了 `nodejs_compat` 兼容性标志
2. 检查构建命令是否正确
3. 查看构建日志中的具体错误信息
## 📊 数据库监控
在 Cloudflare Dashboard 中可以监控 D1 数据库的使用情况:
1. 进入 **D1** 服务
2. 选择数据库实例
3. 查看 **Metrics** 标签页
4. 监控查询次数、存储使用量等指标
## 🔒 安全建议
1. **密码安全**:使用强密码,避免使用默认密码
2. **环境变量**:敏感信息通过环境变量配置,不要硬编码
3. **用户注册**:根据需要开启或关闭用户注册功能
4. **访问控制**:考虑使用 Cloudflare Access 进一步控制访问
## 🆕 更新和迁移
当项目更新包含数据库结构变更时:
1. **备份数据**
```bash
wrangler d1 export katelyatv-db --output backup.sql
```
2. **执行迁移**
```bash
wrangler d1 execute katelyatv-db --file=D1_MIGRATION.md的SQL脚本
```
3. **验证功能**:确保所有功能正常工作
## 📚 相关文档
- [D1 数据库迁移文档](./D1_MIGRATION.md)
- [Cloudflare Pages 官方文档](https://developers.cloudflare.com/pages/)
- [D1 数据库文档](https://developers.cloudflare.com/d1/)
- [Wrangler CLI 文档](https://developers.cloudflare.com/workers/wrangler/)
## 💬 需要帮助?
如果在配置过程中遇到问题:
1. 检查本文档的故障排除部分
2. 查看项目的 GitHub Issues
3. 提交新的 Issue 并提供详细的错误信息和配置详情
+119 -40
View File
@@ -1,10 +1,36 @@
# D1 数据库迁移 - 添加跳过配置功能
# D1 数据库迁移 - 添加成人内容过滤和跳过配置功能
如果您已经有一个运行中的 D1 数据库,需要执行以下 SQL 语句来添加跳过配置支持。
如果您已经有一个运行中的 D1 数据库,需要执行以下 SQL 语句来添加成人内容过滤和跳过配置支持。
## 🗄️ 新增表结构
### skip_configs 表
### user_settings 表(成人内容过滤功能 - 必需)
这个表用于存储用户的个人设置,包括成人内容过滤开关:
```sql
-- 创建用户设置表(成人内容过滤功能)
CREATE TABLE IF NOT EXISTS user_settings (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL,
username TEXT NOT NULL,
filter_adult_content BOOLEAN DEFAULT 1,
theme TEXT DEFAULT 'auto',
language TEXT DEFAULT 'zh-CN',
auto_play BOOLEAN DEFAULT 1,
video_quality TEXT DEFAULT 'auto',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
UNIQUE (user_id, username)
);
-- 为用户设置添加索引以优化查询性能
CREATE INDEX IF NOT EXISTS idx_user_settings_user_id ON user_settings(user_id);
CREATE INDEX IF NOT EXISTS idx_user_settings_username ON user_settings(username);
```
### skip_configs 表(跳过功能 - 可选)
这个表用于存储用户的跳过片头片尾配置:
@@ -12,36 +38,26 @@
-- 创建跳过配置表
CREATE TABLE IF NOT EXISTS skip_configs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL,
key TEXT NOT NULL,
source TEXT NOT NULL,
video_id TEXT NOT NULL,
title TEXT NOT NULL,
segments TEXT NOT NULL,
updated_time INTEGER NOT NULL,
UNIQUE(username, key)
user_id INTEGER NOT NULL,
config_key TEXT NOT NULL,
start_time INTEGER DEFAULT 0,
end_time INTEGER DEFAULT 0,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
UNIQUE (user_id, config_key)
);
-- 为跳过配置添加索引以优化查询性能
CREATE INDEX IF NOT EXISTS idx_skip_configs_username ON skip_configs(username);
CREATE INDEX IF NOT EXISTS idx_skip_configs_username_key ON skip_configs(username, key);
CREATE INDEX IF NOT EXISTS idx_skip_configs_username_updated_time ON skip_configs(username, updated_time DESC);
-- 创建用户设置表(成人内容过滤功能)
CREATE TABLE IF NOT EXISTS user_settings (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL UNIQUE,
settings TEXT NOT NULL,
updated_time INTEGER NOT NULL
);
-- 为用户设置添加索引以优化查询性能
CREATE INDEX IF NOT EXISTS idx_user_settings_username ON user_settings(username);
CREATE INDEX IF NOT EXISTS idx_user_settings_updated_time ON user_settings(updated_time DESC);
CREATE INDEX IF NOT EXISTS idx_skip_configs_user_id ON skip_configs(user_id);
```
## 🚀 执行迁移的方法
### ⚠️ 重要提示
如果您在 Cloudflare Pages 使用成人内容过滤功能时遇到"获取用户设置失败"错误,这是因为缺少 `user_settings` 表。**必须执行此迁移**才能使功能正常工作。
### 方法一:使用 Cloudflare Dashboard(推荐)
1. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com/)
@@ -59,33 +75,96 @@ CREATE INDEX IF NOT EXISTS idx_user_settings_updated_time ON user_settings(updat
# 首先登录 Cloudflare
wrangler auth login
# 创建迁移文件
echo "-- 上面的SQL代码" > user_settings_migration.sql
# 执行数据库迁移
wrangler d1 execute your-database-name --file=migration.sql
wrangler d1 execute your-database-name --file=user_settings_migration.sql
```
其中 `migration.sql` 包含上面的 SQL 代码。
### 方法三:使用项目内置迁移脚本
### 方法三:通过 Pages 函数执行(高级)
```bash
# 克隆或更新项目代码
git pull origin main
也可以创建一个临时的迁移函数,部署后访问来执行迁移。
# 执行完整的D1初始化(包含新表)
wrangler d1 execute your-database-name --file=./scripts/d1-init.sql
```
## 📋 字段说明
| 字段名 | 类型 | 说明 |
| -------------- | ------- | ------------------------------- |
| `id` | INTEGER | 主键,自动递增 |
| `username` | TEXT | 用户名,关联到用户 |
| `key` | TEXT | 配置键,格式:`source+video_id` |
| `source` | TEXT | 视频源标识 |
| `video_id` | TEXT | 视频 ID |
| `title` | TEXT | 视频标题 |
| `segments` | TEXT | 跳过片段数据(JSON 格式) |
| `updated_time` | INTEGER | 更新时间戳 |
### user_settings 表字段
| 字段名 | 类型 | 默认值 | 说明 |
| ----------------------- | -------- | ------- | ------------------------- |
| `id` | INTEGER | 自增 | 主键 |
| `user_id` | INTEGER | 无 | 用户ID,关联users表 |
| `username` | TEXT | 无 | 用户名 |
| `filter_adult_content` | BOOLEAN | 1(true) | 成人内容过滤开关 |
| `theme` | TEXT | 'auto' | 界面主题设置 |
| `language` | TEXT | 'zh-CN' | 语言设置 |
| `auto_play` | BOOLEAN | 1(true) | 自动播放开关 |
| `video_quality` | TEXT | 'auto' | 视频质量偏好 |
| `created_at` | DATETIME | 当前时间 | 创建时间 |
| `updated_at` | DATETIME | 当前时间 | 更新时间 |
### skip_configs 表字段
| 字段名 | 类型 | 默认值 | 说明 |
| ------------- | -------- | -------- | ------------------------- |
| `id` | INTEGER | 自增 | 主键 |
| `user_id` | INTEGER | 无 | 用户ID,关联users表 |
| `config_key` | TEXT | 无 | 配置键,格式:`source+video_id` |
| `start_time` | INTEGER | 0 | 跳过开始时间(秒) |
| `end_time` | INTEGER | 0 | 跳过结束时间(秒) |
| `created_at` | DATETIME | 当前时间 | 创建时间 |
| `updated_at` | DATETIME | 当前时间 | 更新时间 |
## ✅ 迁移验证
执行迁移后,可以通过以下 SQL 验证表是否创建成功:
```sql
-- 检查 user_settings 表是否存在
SELECT name FROM sqlite_master WHERE type='table' AND name='user_settings';
-- 检查 skip_configs 表是否存在
SELECT name FROM sqlite_master WHERE type='table' AND name='skip_configs';
-- 查看 user_settings 表结构
PRAGMA table_info(user_settings);
-- 查看 skip_configs 表结构
PRAGMA table_info(skip_configs);
```
## 🔧 故障排除
### 1. "获取用户设置失败" 错误
**原因**:缺少 `user_settings`
**解决**:执行上述迁移SQL,确保user_settings表已创建
### 2. "表已存在" 错误
**原因**:表已经创建过了
**解决**:这是正常的,`CREATE TABLE IF NOT EXISTS` 语句是安全的
### 3. 外键约束错误
**原因**users表不存在或结构不匹配
**解决**:确保先运行完整的 `./scripts/d1-init.sql` 初始化脚本
## 📞 需要帮助?
如果在迁移过程中遇到问题:
1. 检查 Cloudflare D1 Dashboard 中的数据库状态
2. 确认环境变量 `NEXT_PUBLIC_STORAGE_TYPE=d1` 已设置
3. 验证 `wrangler.toml` 中的数据库配置
4. 查看项目 Issues 或提交新的问题报告
```sql
-- 检查表是否存在
SELECT name FROM sqlite_master WHERE type='table' AND name='skip_configs';
+53 -1
View File
@@ -596,12 +596,59 @@ docker run -d \
- 默认开启过滤,确保安全浏览体验
- 支持资源分组显示,避免误触
**⚠️ 重要部署要求**
成人内容过滤功能需要服务器端存储支持,**不能使用 `localstorage` 存储类型**。
| 部署平台 | 推荐存储类型 | 配置要求 |
| -------------- | ------------ | ---------------------- |
| Docker | `redis` / `kvrocks` | 配置 Redis/Kvrocks 服务器 |
| Vercel | `upstash` | 配置 Upstash Redis |
| Cloudflare Pages | `d1` | 配置 D1 数据库 |
**Cloudflare Pages 特殊配置**
如果你使用 Cloudflare Pages 部署,**必须配置 D1 数据库**才能使用成人内容过滤功能:
1. **创建 D1 数据库**
```bash
wrangler d1 create katelyatv-db
```
2. **初始化数据库表**
```bash
wrangler d1 execute katelyatv-db --file=./scripts/d1-init.sql
```
3. **配置环境变量**
```bash
NEXT_PUBLIC_STORAGE_TYPE=d1
```
4. **更新 wrangler.toml**
```toml
[[d1_databases]]
binding = "DB"
database_name = "katelyatv-db"
database_id = "your-d1-database-id"
```
**故障排除**
- ❌ **错误**"获取用户设置失败"
- **原因**:使用了 `localstorage` 存储类型,服务器端API无法访问
- **解决**:按上述要求配置数据库存储
- ❌ **错误**:过滤开关无法保存
- **原因**:存储后端未正确配置或连接失败
- **解决**:检查数据库连接和环境变量配置
**使用方法**
1. **访问用户设置**
- 登录后访问 `/settings` 页面
- 或在用户菜单中点击「用户设置
- 或在用户菜单中点击「内容过滤
2. **配置过滤选项**
@@ -639,6 +686,11 @@ docker run -d \
- 关闭过滤功能需要用户主动操作,确保使用意图明确
- 建议管理员在配置资源站时准确标记 `is_adult` 字段
**详细配置指南**
- 📖 [Cloudflare Pages 成人内容过滤配置指南](./CLOUDFLARE_PAGES_ADULT_FILTER.md)
- 🗄️ [D1 数据库迁移说明](./D1_MIGRATION.md)
### 🎯 跳过片头片尾
**功能介绍**
+18
View File
@@ -68,6 +68,22 @@ CREATE TABLE IF NOT EXISTS skip_configs (
UNIQUE (user_id, config_key)
);
-- 用户设置表
CREATE TABLE IF NOT EXISTS user_settings (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL,
username TEXT NOT NULL,
filter_adult_content BOOLEAN DEFAULT 1,
theme TEXT DEFAULT 'auto',
language TEXT DEFAULT 'zh-CN',
auto_play BOOLEAN DEFAULT 1,
video_quality TEXT DEFAULT 'auto',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
UNIQUE (user_id, username)
);
-- 管理员配置表
CREATE TABLE IF NOT EXISTS admin_configs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -92,6 +108,8 @@ CREATE INDEX IF NOT EXISTS idx_play_records_record_key ON play_records(record_ke
CREATE INDEX IF NOT EXISTS idx_favorites_user_id ON favorites(user_id);
CREATE INDEX IF NOT EXISTS idx_search_history_user_id ON search_history(user_id);
CREATE INDEX IF NOT EXISTS idx_skip_configs_user_id ON skip_configs(user_id);
CREATE INDEX IF NOT EXISTS idx_user_settings_user_id ON user_settings(user_id);
CREATE INDEX IF NOT EXISTS idx_user_settings_username ON user_settings(username);
-- 创建视图以简化查询
CREATE VIEW IF NOT EXISTS user_stats AS