eepmoody/open5e-api

Open5e API 镜像文档

镜像概述和主要用途

Open5e API是一个基于OGL（开放游戏许可）构建的D&D 5e规则资源接口，提供D&D 5e游戏系统的JSON数据服务。该项目由社区志愿者驱动，使用Django REST Framework开发，具备可浏览性和CRUD端点开发便利性，默认使用SQLite数据库，数据来源于/data目录。

核心功能和特性

• D&D 5e数据接口：提供D&D 5e游戏系统的各类规则数据，包括怪物、法术、装备等
• 可浏览API：基于Django REST Framework实现的直观浏览界面
• 搜索功能：支持游戏内容的搜索索引和查询
• OAS文件生成：可导出OpenAPI规范文件，便于第三方应用集成
• 灵活部署：支持本地开发、自托管和云平台部署

使用场景和适用范围

• 桌面和移动D&D 5e辅助工具开发
• D&D 5e游戏资源网站后端
• 游戏主持人(DM)工具的数据来源
• 个人D&D 5e规则查询服务自托管

详细使用方法和配置说明

系统要求

• Python 3.11
• Pipenv
• Docker（容器化部署时）

本地开发环境搭建

依赖安装

bash
# 克隆项目后安装依赖
pipenv install --dev

构建本地数据库

创建本地数据库并导入游戏内容：

bash
# 不包含搜索索引的快速构建
pipenv run python manage.py quicksetup --noindex

# 包含搜索索引的完整构建（启用搜索功能需执行此命令）
pipenv run python manage.py quicksetup

注意：当添加/删除/编辑游戏内容、修改Python代码或切换git分支后，需重新执行上述构建命令。

运行开发服务器

bash
# 启动本地开发服务器（仅用于开发，不建议生产环境使用）
# 服务将在 http://localhost:8000 可用
pipenv run python manage.py runserver

自托管配置

如需本地自托管，建议使用gunicorn作为WSGI服务器：

bash
# 启动自托管服务器，服务将在 http://localhost:8888 可用
gunicorn -b :8888 server.wsgi:application

生成OAS文件

构建完成后，可生成OpenAPI规范文件：

bash
pipenv run python manage.py spectacular --color --file openapi-schema.yml

测试

测试文件位于api/tests目录，运行测试前需确保API已在http://localhost:8000启动：

bash
pipenv run pytest

审批测试说明

• 审批测试基于api/tests/approved_files目录中的*.approved.*文件
• 测试失败时，接收的输入将存储在*.recieved.*文件中
• 如需批准变更，将旧的*.approved.*文件替换为*.recieved.*文件
• *.recieved.*文件不应提交到git仓库

部署指南

Docker部署

构建镜像

bash
docker build -t open5e-api .

运行容器

bash
# 基本运行
docker run -d -p 8888:8888 --name open5e-api open5e-api

# 带环境变量配置
docker run -d -p 8888:8888 \
  -e SECRET_KEY="your_secret_key" \
  -e SERVER_NAME="api.yourdomain.com" \
  --name open5e-api open5e-api

Docker Compose部署

yaml
version: '3'
services:
  open5e-api:
    build: .
    ports:
      - "8888:8888"
    environment:
      - SECRET_KEY="your_secret_key"
      - SERVER_NAME="api.yourdomain.com"
    restart: unless-stopped

云平台部署

DigitalOcean部署

bash
# 在Droplet上部署
git pull https://github.com/open5e/open5e-api
export SECRET_KEY="your_new_secret_key"
export SERVER_NAME="whatever.yourdomain.com"
cd open5e-api/
docker-compose up

Railway.app部署

1. 在GitHub上创建项目分支
2. 在Railway.app登录GitHub账号并授权访问分支
3. 创建新项目并选择"从GitHub仓库部署"，选择目标分支
4. 接受默认设置，允许Railway复制仓库中的现有变量
5. 添加环境变量PORT=8888
6. 添加环境变量SERVER_NAME（使用Railway提供的域名或自定义域名）
7. 推送提交到GitHub，系统将自动部署

环境变量配置

贡献指南

详见项目根目录的CONTRIBUTING.md文件。