From db08179eb063ab90cc562a2273be38ecb98f32bb Mon Sep 17 00:00:00 2001
From: katelya <katelya77@gmail.com>
Date: Thu, 4 Sep 2025 22:55:28 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=88=90=E4=BA=BA?=
 =?UTF-8?q?=E5=86=85=E5=AE=B9=E8=BF=87=E6=BB=A4=E5=8A=9F=E8=83=BD=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E5=92=8C=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

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

 问题修复:
- 解决Cloudflare Pages部署时'获取用户设置失败'错误
- 明确说明不同部署平台的存储类型要求
- 提供详细的故障排除指南
---
 CLOUDFLARE_PAGES_ADULT_FILTER.md | 194 +++++++++++++++++++++++++++++++
 D1_MIGRATION.md                  | 159 ++++++++++++++++++-------
 README.md                        |  54 ++++++++-
 scripts/d1-init.sql              |  18 +++
 4 files changed, 384 insertions(+), 41 deletions(-)
 create mode 100644 CLOUDFLARE_PAGES_ADULT_FILTER.md

diff --git a/CLOUDFLARE_PAGES_ADULT_FILTER.md b/CLOUDFLARE_PAGES_ADULT_FILTER.md
new file mode 100644
index 0000000..c050a84
--- /dev/null
+++ b/CLOUDFLARE_PAGES_ADULT_FILTER.md
@@ -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 并提供详细的错误信息和配置详情
diff --git a/D1_MIGRATION.md b/D1_MIGRATION.md
index eddbc66..bd63312 100644
--- a/D1_MIGRATION.md
+++ b/D1_MIGRATION.md
@@ -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';
diff --git a/README.md b/README.md
index 71872d2..8b784ed 100644
--- a/README.md
+++ b/README.md
@@ -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)
+
 ### 🎯 跳过片头片尾
 
 **功能介绍**：
diff --git a/scripts/d1-init.sql b/scripts/d1-init.sql
index 171dea4..d71f021 100644
--- a/scripts/d1-init.sql
+++ b/scripts/d1-init.sql
@@ -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