5个步骤掌握oTree：从环境搭建到实验部署完全指南

oTree是一款开源实验平台，作为专业的经济学研究工具，它基于Python实验框架构建，能够帮助研究者快速开发和部署在线行为实验。本文将通过五个关键步骤，带您从环境准备到成功运行经济学实验，无论您是实验经济学新手还是有经验的开发者，都能通过本指南掌握oTree的核心配置方法。

一、价值定位：为什么选择oTree进行实验研究

在行为经济学研究中，可靠的实验工具是确保研究结果准确性的基础。oTree作为专为实验设计的Python框架，具有三大核心优势：首先，它提供了完整的实验生命周期管理，从被试招募到数据收集全程自动化；其次，基于Django的架构确保了实验界面的高定制性，研究者可根据需求设计复杂的交互场景；最后，内置的实时数据同步功能，让多被试同时在线实验成为可能。与传统实验室实验相比，oTree将实验部署成本降低60%以上，同时支持全球范围内的被试招募，显著提升研究效率。

二、技术选型：oTree核心组件及其作用

oTree的强大功能源于其精心设计的技术栈，各组件协同工作确保实验流畅运行：

• Python 3.6+：提供类型注解支持，确保代码健壮性，同时支持异步编程特性，提升并发处理能力
• Django：作为Web框架核心，负责URL路由、模板渲染和请求处理，采用MTV（Model-Template-View）架构分离业务逻辑与界面展示
• Channels：就像实验室内的即时通讯系统，通过WebSocket实现实时双向通信，确保多被试间的同步交互
• Bootstrap：提供响应式布局支持，使实验界面在电脑、平板和手机等不同设备上都能良好展示
• MySQL：作为关系型数据库，负责存储实验设计参数、被试行为数据和实验结果，支持复杂查询和事务处理

三、环境准备：如何验证你的系统是否满足要求

在开始安装前，请确保您的系统满足以下条件。建议使用Linux或macOS系统以获得最佳兼容性，Windows用户可能需要额外配置WSL环境。

[!NOTE] 所有命令均在终端中执行，Linux/macOS用户可使用系统自带终端，Windows用户建议使用PowerShell或WSL终端。

核心依赖检查清单

依赖项	最低版本	验证命令	备注
Python	3.6	python --version 或 python3 --version	推荐3.8+以获得更好性能
pip	19.0	pip --version 或 pip3 --version	Python包管理工具
MySQL	5.7	mysql --version	或使用MariaDB 10.2+
git	2.0	git --version	用于代码获取

环境验证步骤

1. 检查Python版本：

python3 --version  # 查看Python版本，应输出3.6.0或更高版本

2. 验证pip是否安装：

pip3 --version  # 确保输出pip 19.0或更高版本

3. 检查MySQL服务状态：

systemctl status mysql  # Linux系统检查服务状态
# 或
brew services list | grep mysql  # macOS(Homebrew)检查服务状态

[!TIP] 如果MySQL未运行，可使用systemctl start mysql(Linux)或brew services start mysql(macOS)启动服务。Windows用户可通过服务管理器启动MySQL服务。

四、分步实施：从基础配置到性能调优

4.1 基础配置：获取与安装核心程序

步骤1：获取项目代码

git clone https://gitcode.com/gh_mirrors/otr/oTree  # 克隆项目仓库
cd oTree  # 进入项目目录

步骤2：创建虚拟环境

python3 -m venv venv  # 创建名为venv的虚拟环境
source venv/bin/activate  # 激活虚拟环境(Linux/macOS)
# 或
venv\Scripts\activate  # Windows系统激活命令

[!NOTE] 激活虚拟环境后，终端提示符前会显示(venv)，表示当前处于虚拟环境中。所有后续命令均需在此环境下执行。

步骤3：安装依赖包

pip install -r requirements.txt  # 安装生产环境依赖
pip install -r requirements-dev.txt  # 可选：安装开发环境依赖(包含测试工具)

4.2 高级功能：数据库配置与初始化

步骤1：创建数据库

mysql -u root -p  # 登录MySQL，执行后输入密码

在MySQL命令行中执行：

CREATE DATABASE otree DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'otreeuser'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON otree.* TO 'otreeuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

步骤2：配置数据库连接

编辑项目目录中的settings.py文件，找到DATABASES配置项，修改为：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'otree',
        'USER': 'otreeuser',
        'PASSWORD': 'your_secure_password',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'"
        }
    }
}

步骤3：初始化数据库

python manage.py migrate  # 创建数据库表结构
python manage.py createsuperuser  # 创建管理员账户，按提示输入用户名、邮箱和密码

4.3 性能调优：提升实验运行效率

配置缓存系统

在settings.py中添加缓存配置，提升页面加载速度：

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
        'LOCATION': 'unique-snowflake',
        'TIMEOUT': 300,  # 缓存超时时间(秒)
    }
}

启用异步任务处理

安装Celery提升并发处理能力：

pip install celery redis  # 安装Celery和Redis依赖

创建celery.py文件，配置异步任务队列：

from celery import Celery
import os

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'settings')
app = Celery('otree')
app.config_from_object('django.conf:settings', namespace='CELERY')
app.autodiscover_tasks()

五、问题解决：常见故障排除指南

数据库连接失败

症状：执行migrate命令时提示"Can't connect to MySQL server"
解决方案：

1. 检查MySQL服务是否运行：systemctl status mysql
2. 验证数据库凭据是否正确：mysql -u otreeuser -p
3. 检查防火墙设置：sudo ufw allow 3306(仅Linux)

依赖包安装错误

症状：pip install时出现编译错误
解决方案：

• Ubuntu/Debian: sudo apt-get install python3-dev libmysqlclient-dev
• CentOS/RHEL: sudo yum install python3-devel mysql-devel
• macOS: brew install mysql-connector-c

开发服务器启动失败

症状：python manage.py runserver提示端口被占用
解决方案：

python manage.py runserver 8001  # 使用8001端口启动
# 或查找占用进程并终止
lsof -i :8000  # 查找占用8000端口的进程ID
kill -9 <进程ID>  # 终止占用进程

[!TIP] 完整错误日志位于项目目录的otree.log文件中，遇到问题时可查看该文件获取详细信息。

总结与下一步

通过以上五个步骤，您已完成oTree的基础安装与配置。现在可以通过以下命令启动开发服务器：

python manage.py runserver  # 默认在8000端口启动

在浏览器中访问http://127.0.0.1:8000/即可进入oTree管理界面。

接下来，您可以：

1. 通过管理员界面(http://127.0.0.1:8000/admin)创建实验会话
2. 参考bargaining、dictator等示例应用学习实验设计
3. 查阅官方文档了解高级功能，如被试招募、支付集成和数据导出

oTree作为灵活强大的实验经济学工具，为您的研究提供了坚实的技术基础。随着使用深入，您将发现其更多定制化功能，助力您的实验研究达到新高度。