EnderRealm 技术文档

外观

后端服务 ​

EnderRealm 使用 Python FastAPI 后端服务来管理 i18n 文本、环境配置等。这个章节将教你如何启动后端服务。

什么是后端服务？ ​

后端服务是一个独立的服务，为服务器插件提供数据支持，包括但不限于配置管理、国际化文本存储等功能。

提示

关于后端服务的详细 API 文档和功能说明，请参考文档站的其他章节。

后端技术栈 ​

技术版本用途
Python3.12+编程语言
FastAPI0.115.0+Web 框架
uvicorn0.34.0+ASGI 服务器
asyncpg0.30.0+PostgreSQL 驱动
uv最新版包管理工具

启动后端服务 ​

步骤 1：安装依赖 ​

首先，安装 Python 依赖：

bash
# 进入后端目录
cd EnderRealmServerApi

# 安装 uv（如果尚未安装）
pip install uv

# 安装依赖
uv sync

uv sync 会：

  1. 创建虚拟环境（如果不存在）
  2. 安装 pyproject.toml 中定义的所有依赖
  3. 生成 uv.lock 锁定文件

步骤 2：配置环境变量 ​

复制环境变量模板：

bash
# 复制模板
cp .env.example .env

编辑 .env 文件，配置数据库连接：

env
# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_NAME=enderrealm
DB_USER=enderrealm
DB_PASSWORD=your_password

# 环境配置
ENVIRONMENT=development

# 服务器配置（可选）
SERVER_NAME=dev-server
SERVER_REGION=local

步骤 3：初始化数据库 ​

如果尚未初始化数据库，执行以下命令：

bash
# 创建数据库
psql -U postgres -f ../database/init_db.sql

# 初始化表结构
psql -U postgres -d enderrealm -f ../database/init_schema.sql

# 导入 i18n 数据
psql -U postgres -d enderrealm -f ../database/i18n.sql

步骤 4：启动服务 ​

bash
# 启动服务（开发模式，支持热重载）
uv run uvicorn app.main:app --reload

# 或者指定端口
uv run uvicorn app.main:app --reload --port 8000

# 或者指定主机和端口
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

你会看到类似输出：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

提示

服务启动后，可以通过 http://127.0.0.1:8000 访问 API。

验证后端服务 ​

访问健康检查端点 ​

bash
# 使用 curl
curl http://127.0.0.1:8000/v1/health/

# 使用 PowerShell
Invoke-WebRequest -Uri http://127.0.0.1:8000/v1/health/

应该返回：

json
{
  "status": "healthy",
  "database": {
    "connected": true,
    "version": "PostgreSQL 16.x"
  }
}

访问 API 文档 ​

查看 API 文档 ​

FastAPI 自动生成 API 文档：

警告

API 文档默认禁用，需要配置 API 密钥才能访问。

后端与服务器的通信 ​

EnderRealmServerCore 通过 HTTP 与后端通信：

Minecraft 服务器
    ↓ HTTP 请求
EnderRealmServerApi（Python 后端）
    ↓ SQL 查询
PostgreSQL 数据库

配置后端地址 ​

在 EnderRealmServerCore/config.yml 中配置：

yaml
backend:
  url: "http://localhost:8000"
  api-key: "your-api-key"
  connect-timeout: 5000
  request-timeout: 10000
  max-retries: 3

常见问题 ​

Q: 启动失败，提示模块未找到？ ​

A: 确保已安装依赖：

bash
cd EnderRealmServerApi
uv sync

Q: 启动失败，提示数据库连接失败？ ​

A: 检查以下几点：

  1. PostgreSQL 服务是否启动
  2. 数据库配置是否正确
  3. 数据库和用户是否创建

Q: 如何查看后端日志？ ​

A: 后端日志直接输出到控制台，包含请求信息和错误信息。

Q: 如何重启后端服务？ ​

A: 在终端按 Ctrl+C 停止服务，然后重新启动：

bash
uv run uvicorn app.main:app --reload

Q: 如何在后台运行后端服务？ ​

A: 使用以下方法：

bash
# Linux/macOS
nohup uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 &

# Windows（使用 PowerShell Start-Process）
Start-Process -NoNewWindow uv "run uvicorn app.main:app --host 0.0.0.0 --port 8000"

后端开发最佳实践 ​

1. 使用热重载 ​

开发时使用 --reload 参数，修改代码后自动重启。

2. 查看 API 文档 ​

访问 http://127.0.0.1:8000/docs 查看 API 文档。

3. 使用环境变量 ​

敏感配置使用环境变量，不要提交到代码库。

4. 运行类型检查 ​

bash
# 运行 pyright 类型检查
uv run pyright

恭喜！ ​

你已经完成了"从零到一"教程的所有内容！现在你应该能够：

  • 搭建完整的开发环境
  • 获取和理解项目代码
  • 构建和运行项目
  • 启动后端服务

下一步 ​

现在你可以开始参与 EnderRealm 项目开发了！建议：

  1. 查看 快速开始 了解更多细节
  2. 浏览 目录 查看所有文档

祝你开发愉快！

© 2022-present EnderRealm. All rights reserved.