# 服务器端安装指南

## 🚀 快速部署 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