taiko-web/SERVER_INSTALL.md

服务器端安装指南

🚀 快速部署 Taiko Web (Sorted 分支)

---

📋 前置要求

• Ubuntu/Debian Linux 服务器
• Python 3.8+
• Git
• MongoDB
• Redis

---

🔧 完整安装步骤

1. 克隆 Sorted 分支

# 克隆代码（包含智能排序功能）
git clone -b Sorted https://git.20091128.xyz/AnthonyDuan/taiko-web.git
cd taiko-web

2. 创建虚拟环境

# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate

3. 安装依赖（分步骤）

步骤 A: 先安装基础依赖

# 安装除 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: 使用安装脚本（推荐）

# 给脚本执行权限
chmod +x install_tjaf.sh

# 运行安装脚本
./install_tjaf.sh

方法 2: 使用 GitHub 镜像

# 尝试通过镜像安装
pip install git+https://ghproxy.com/https://github.com/yuukiwww/tjaf.git@d59e854b074012f6a31bd4c65b53edb6148b0ac7

方法 3: 跳过 tjaf（如果暂时不需要 TJA 功能）

# 直接跳过，稍后手动处理
echo "跳过 tjaf 安装，稍后处理"

4. 配置应用

# 复制配置文件
cp config.example.py config.py

# 编辑配置
nano config.py
# 根据你的环境修改 MongoDB、Redis 等配置

5. 启动服务

开发模式

# 激活虚拟环境（如果还没激活）
source .venv/bin/activate

# 启动 Flask 开发服务器
flask run --host=0.0.0.0 --port=5000

生产模式（使用 Gunicorn）

# 使用 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 文件：

# 如果有 tjaf 源代码
mkdir -p tjaf
# 将源代码复制到 tjaf/ 目录
pip install -e ./tjaf

# 如果有 wheel 文件
pip install /path/to/tjaf-*.whl

🔄 推荐方案 2: 使用镜像站

# 中国大陆用户推荐使用 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 解析功能：

# 编辑 app.py
nano app.py

# 找到并注释以下行:
# import tjaf
# 以及使用 tjaf 的代码（第 835 行左右）

---

📊 验证安装

检查依赖

# 查看已安装的包
pip list

# 检查是否安装了所有必需的包
pip check

测试应用

# 启动应用
flask run

# 在另一个终端测试
curl http://localhost:5000

测试智能排序功能

1. 访问 http://your-server:5000
2. 查看歌曲列表
3. 应该看到歌曲已按 数字 → 字母 → 其他 的顺序排列

---

🐳 Docker 部署（可选）

如果你想使用 Docker：

# 构建镜像
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: 虚拟环境激活失败

解决方法:

# 确保正确创建虚拟环境
python3 -m venv .venv

# 使用完整路径激活
source /root/taiko-web/.venv/bin/activate

问题 3: 权限问题

解决方法:

# 修改文件权限
chmod +x install_tjaf.sh
chmod -R 755 /root/taiko-web

问题 4: MongoDB 连接失败

解决方法:

# 检查 MongoDB 是否运行
systemctl status mongod

# 启动 MongoDB
systemctl start mongod

# 修改 config.py 中的连接字符串

---

📞 获取帮助

查看日志

# Flask 日志
flask run --debug

# Gunicorn 日志
gunicorn --access-logfile - --error-logfile - server:app

相关文档

• 📖 TJAF 安装说明
• 📘 排序功能使用指南
• 🚀 快速开始

---

✅ 完整安装命令（复制粘贴）

# 克隆代码
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