docs: 添加服务器端安装指南

- 详细的部署步骤说明 - tjaf 依赖问题的多种解决方案 - 故障排除指南 - 一键安装命令
2025-11-15 16:26:07 +08:00
parent 704d4c7522
commit 1b9d2a032c
1 changed files with 329 additions and 0 deletions
--- a/SERVER_INSTALL.md
+++ b/SERVER_INSTALL.md
@@ -0,0 +1,329 @@
+# 服务器端安装指南
+
+## 🚀 快速部署 Taiko Web (Sorted 分支)
+
+---
+
+## 📋 前置要求
+
+- Ubuntu/Debian Linux 服务器
+- Python 3.8+
+- Git
+- MongoDB
+- Redis
+
+---
+
+## 🔧 完整安装步骤
+
+### 1. 克隆 Sorted 分支
+
+```bash
+# 克隆代码（包含智能排序功能）
+git clone -b Sorted https://git.20091128.xyz/AnthonyDuan/taiko-web.git
+cd taiko-web
+```
+
+### 2. 创建虚拟环境
+
+```bash
+# 创建虚拟环境
+python3 -m venv .venv
+
+# 激活虚拟环境
+source .venv/bin/activate
+```
+
+### 3. 安装依赖（分步骤）
+
+#### 步骤 A: 先安装基础依赖
+
+```bash
+# 安装除 tjaf 外的所有依赖
+pip install bcrypt==4.2.1 \
+    ffmpy==0.5.0 \
+    Flask==3.1.0 \
+    Flask-Caching==2.3.0 \
+    Flask-Session==0.8.0 \
+    Flask-WTF==1.2.2 \
+    gunicorn==23.0.0 \
+    jsonschema==4.23.0 \
+    pymongo==4.11 \
+    redis==5.2.1 \
+    requests==2.32.3 \
+    websockets==14.2 \
+    Flask-Limiter==3.10.1 \
+    msgspec==0.19.0
+```
+
+#### 步骤 B: 安装 tjaf 包
+
+**方法 1: 使用安装脚本（推荐）**
+
+```bash
+# 给脚本执行权限
+chmod +x install_tjaf.sh
+
+# 运行安装脚本
+./install_tjaf.sh
+```
+
+**方法 2: 使用 GitHub 镜像**
+
+```bash
+# 尝试通过镜像安装
+pip install git+https://ghproxy.com/https://github.com/yuukiwww/tjaf.git@d59e854b074012f6a31bd4c65b53edb6148b0ac7
+```
+
+**方法 3: 跳过 tjaf（如果暂时不需要 TJA 功能）**
+
+```bash
+# 直接跳过，稍后手动处理
+echo "跳过 tjaf 安装，稍后处理"
+```
+
+### 4. 配置应用
+
+```bash
+# 复制配置文件
+cp config.example.py config.py
+
+# 编辑配置
+nano config.py
+# 根据你的环境修改 MongoDB、Redis 等配置
+```
+
+### 5. 启动服务
+
+#### 开发模式
+
+```bash
+# 激活虚拟环境（如果还没激活）
+source .venv/bin/activate
+
+# 启动 Flask 开发服务器
+flask run --host=0.0.0.0 --port=5000
+```
+
+#### 生产模式（使用 Gunicorn）
+
+```bash
+# 使用 Gunicorn 启动
+gunicorn -w 4 -b 0.0.0.0:5000 server:app
+```
+
+---
+
+## ⚠️ tjaf 包问题解决方案
+
+### 问题描述
+
+`tjaf` 包的 GitHub 仓库目前不可访问，安装时会报错：
+
+```
+fatal: Authentication failed for 'https://github.com/yuukiwww/tjaf.git/'
+```
+
+### 解决方案选择
+
+#### 🎯 推荐方案 1: 使用本地副本
+
+如果你有 tjaf 的源代码或 wheel 文件：
+
+```bash
+# 如果有 tjaf 源代码
+mkdir -p tjaf
+# 将源代码复制到 tjaf/ 目录
+pip install -e ./tjaf
+
+# 如果有 wheel 文件
+pip install /path/to/tjaf-*.whl
+```
+
+#### 🔄 推荐方案 2: 使用镜像站
+
+```bash
+# 中国大陆用户推荐使用 ghproxy
+pip install git+https://ghproxy.com/https://github.com/yuukiwww/tjaf.git@d59e854b074012f6a31bd4c65b53edb6148b0ac7
+
+# 或者其他镜像
+pip install git+https://mirror.ghproxy.com/https://github.com/yuukiwww/tjaf.git@d59e854b074012f6a31bd4c65b53edb6148b0ac7
+```
+
+#### 🚧 临时方案 3: 注释相关代码
+
+如果暂时不需要 TJA 解析功能：
+
+```bash
+# 编辑 app.py
+nano app.py
+
+# 找到并注释以下行:
+# import tjaf
+# 以及使用 tjaf 的代码（第 835 行左右）
+```
+
+---
+
+## 📊 验证安装
+
+### 检查依赖
+
+```bash
+# 查看已安装的包
+pip list
+
+# 检查是否安装了所有必需的包
+pip check
+```
+
+### 测试应用
+
+```bash
+# 启动应用
+flask run
+
+# 在另一个终端测试
+curl http://localhost:5000
+```
+
+### 测试智能排序功能
+
+1. 访问 http://your-server:5000
+2. 查看歌曲列表
+3. 应该看到歌曲已按 **数字 → 字母 → 其他** 的顺序排列
+
+---
+
+## 🐳 Docker 部署（可选）
+
+如果你想使用 Docker：
+
+```bash
+# 构建镜像
+docker build -t taiko-web .
+
+# 运行容器
+docker run -d \
+  -p 5000:5000 \
+  --name taiko-web \
+  -e MONGODB_URI=mongodb://your-mongo:27017 \
+  -e REDIS_URL=redis://your-redis:6379 \
+  taiko-web
+```
+
+---
+
+## 🔍 故障排除
+
+### 问题 1: tjaf 安装失败
+
+**错误信息:**
+```
+fatal: Authentication failed for 'https://github.com/yuukiwww/tjaf.git/'
+```
+
+**解决方法:**
+1. 使用 GitHub 镜像站（见上文）
+2. 使用本地 tjaf 副本
+3. 暂时跳过 tjaf 安装
+
+### 问题 2: 虚拟环境激活失败
+
+**解决方法:**
+```bash
+# 确保正确创建虚拟环境
+python3 -m venv .venv
+
+# 使用完整路径激活
+source /root/taiko-web/.venv/bin/activate
+```
+
+### 问题 3: 权限问题
+
+**解决方法:**
+```bash
+# 修改文件权限
+chmod +x install_tjaf.sh
+chmod -R 755 /root/taiko-web
+```
+
+### 问题 4: MongoDB 连接失败
+
+**解决方法:**
+```bash
+# 检查 MongoDB 是否运行
+systemctl status mongod
+
+# 启动 MongoDB
+systemctl start mongod
+
+# 修改 config.py 中的连接字符串
+```
+
+---
+
+## 📞 获取帮助
+
+### 查看日志
+
+```bash
+# Flask 日志
+flask run --debug
+
+# Gunicorn 日志
+gunicorn --access-logfile - --error-logfile - server:app
+```
+
+### 相关文档
+
+- 📖 [TJAF 安装说明](TJAF_INSTALL.md)
+- 📘 [排序功能使用指南](SORT_USAGE.md)
+- 🚀 [快速开始](QUICKSTART_SORT.md)
+
+---
+
+## ✅ 完整安装命令（复制粘贴）
+
+```bash
+# 克隆代码
+git clone -b Sorted https://git.20091128.xyz/AnthonyDuan/taiko-web.git
+cd taiko-web
+
+# 创建虚拟环境
+python3 -m venv .venv
+source .venv/bin/activate
+
+# 安装基础依赖
+pip install -r requirements.txt 2>/dev/null || echo "部分依赖安装失败"
+
+# 尝试安装 tjaf
+chmod +x install_tjaf.sh
+./install_tjaf.sh || echo "tjaf 需要手动安装"
+
+# 配置应用
+cp config.example.py config.py
+nano config.py  # 修改配置
+
+# 启动应用
+flask run --host=0.0.0.0 --port=5000
+```
+
+---
+
+## 🎉 安装完成！
+
+访问 http://your-server-ip:5000 开始使用 Taiko Web！
+
+歌曲列表已自动按智能顺序排列：
+- 🔢 数字优先
+- 🔤 字母次之
+- 🌏 其他符号最后
+
+**享受游戏！** 🥁
+
+---
+
+**更新时间**: 2025-11-15  
+**分支**: Sorted  
+**版本**: v1.1