XLangAI（小浪AI） · 服务端与运营后台 — 面向多语种口语练习场景的完整后端解决方案
语言：简体中文 · English
官网 · 服务器商店 · GitHub 源码 · 下载客户端
📱 iOS 客户端 | 🏪 官网服务器商店 | 🔧 开源服务端（本仓库）
功能特性 · 架构 · 快速开始 · 本地开发 · 环境变量 · API 概览
XLangAI（英文品牌 XlangAI，意为 all language AI）是一款多语种 AI 口语练习产品。本目录包含可独立部署的服务端与运营后台：Go API 为客户端提供鉴权、对话、语音、计费与媒体接口，Nuxt 运营后台负责语种、模型、会员、提示词与系统配置。
| 子目录 | 说明 | 技术栈 |
|---|---|---|
server/ |
面向 App 的 Go API：鉴权、对话、语音、计费、媒体等 | Go 1.26 · Gin · GORM · PostgreSQL |
manager/ |
运营后台：配置中心、用户与对话管理、数据备份 | Nuxt 4 · Vue 3 · Prisma 7 · PostgreSQL |
本目录不包含 Flutter 客户端与官网（
client、home位于 XLangAI 主仓库的其他目录）。只部署servers/即可支撑 App API 与运营后台。
| 端 | 说明 | 入口 |
|---|---|---|
| 客户端 | 闭源 | xlangai.com/download |
| 官网 · 服务器商店 | 浏览社区公开服务器，复制地址到 App | xlangai.com/servers |
| 开源服务端（本目录） | Docker 部署 API + 运营后台 | 本仓库 |
- 只想部署：从 快速开始 开始，按顺序配置数据库、密钥和管理员账号。
- 本地联调：先启动
manager完成 Prisma 迁移与种子数据，再启动server。 - 排查配置：优先查看 环境变量 与 生产上线检查。
开源协议：MIT
作者：GT · DingDangDog
- 用户与鉴权：注册/登录、短信验证码、Google / Apple 第三方登录、JWT 会话
- 多语种对话：创建会话、文本/语音对话、消息历史、翻译接口
- 语音链路：STT（多协议可配置）→ LLM → TTS；内置 ffmpeg 响度归一化
- 会员与计费：会员档位、应用内购校验（Apple / Google Play）
- 媒体与存储：头像上传、音频试听、对象存储预签名（R2 / S3 / 七牛 / 阿里云 OSS / 本地）
- 可观测性：Gin 访问日志 + 统一
[api]错误日志（见design/server-logging.md）
- 服务配置：LLM / STT / TTS / 翻译 / 对象存储 多服务商管理
- 内容与运营：语种、音色角色、提示词模板、会员档位、系统设置
- 用户域：用户列表、对话与消息、用量统计、注销备份
- 运维：数据库迁移（Nitro 启动时自动执行）、种子数据、备份导出、服务器商店同步
- 单镜像：根目录
Dockerfile构建 Nuxt + Go 一体化镜像 - Docker Compose：一键启动，挂载
storage持久卷 - 分体部署：
server与manager可分别本地或容器运行，共用同一 PostgreSQL
受限于个人维护精力，本项目接入的 LLM、语音（STT/TTS）、短信、对象存储等多种 API 渠道尚未全部完成充分测试，实际使用中可能出现兼容性或稳定性问题，敬请谅解。
若您在使用中遇到问题，欢迎通过 GitHub Issue 反馈，或参与测试、提交 Pull Request，共同完善各渠道的接入质量。
flowchart TB
subgraph clients [客户端]
App[Flutter App]
Browser[运营人员浏览器]
end
subgraph servers [本仓库 servers]
API[Go API :8080]
MGR[Nuxt Manager :3312]
DB[(PostgreSQL)]
Vol[/storage 音频·头像/]
end
subgraph external [外部服务 可配置]
LLM[LLM 服务商]
STT[STT 服务商]
TTS[TTS 服务商]
OSS[对象存储]
end
App --> API
Browser --> MGR
MGR --> DB
API --> DB
MGR -.配置下发.-> API
API --> LLM & STT & TTS
API --> OSS
API --> Vol
MGR --> Vol
| 场景 | 依赖 |
|---|---|
| Docker 部署 | Docker 24+、Docker Compose v2、PostgreSQL 15+（宿主机或容器） |
| 本地开发 API | Go 1.26+、PostgreSQL、可选 Redis |
| 本地开发后台 | Node.js 22+、pnpm 11+、PostgreSQL |
| 语音处理 | ffmpeg（Docker 镜像已内置；本地 STT/TTS 转码需自行安装） |
在宿主机或独立容器中创建 PostgreSQL 数据库（示例库名 xlangai），并记下连接串。
Windows / macOS 容器访问宿主机 Postgres 时，将 DATABASE_URL 主机改为 host.docker.internal（Compose 已配置 extra_hosts）。
在 docker/ 目录创建 .env，至少覆盖数据库、JWT 密钥与首次管理员账号：
DATABASE_URL="postgresql://postgres:your-password@host.docker.internal:5432/xlangai?schema=public"
JWT_SECRET="请替换为足够长的随机字符串"
NUXT_MANAGER_AUTH_SECRET="请替换为另一个足够长的随机字符串"
# HTTP / 内网 Docker 保持 development；公网 HTTPS 部署改为 production
NUXT_ENV="development"
# 首次部署：运营管理员（写入后建议关闭初始化并删除密码变量）
NUXT_MANAGER_ADMIN_USERNAME="admin@example.com"
NUXT_MANAGER_ADMIN_PASSWORD="your-strong-password"
NUXT_MANAGER_ADMIN_NICKNAME="管理员"
JWT_SECRET用于 App 用户会话；NUXT_MANAGER_AUTH_SECRET用于运营后台登录会话。生产环境建议分别设置。
cd servers
docker-compose up -d首次启动时，manager 会先执行 Prisma 迁移和种子数据；完成后 entrypoint.sh 再启动 Go API。
| 服务 | 地址 |
|---|---|
| 运营后台 | http://localhost:3312 |
| Go API | http://localhost:8080 |
| API 健康检查 | http://localhost:8080/api/v1/languages |
变量按职责分组。Nuxt 应用配置走 runtimeConfig，环境变量必须以 NUXT_ / NUXT_PUBLIC_ 开头；Node/Nitro/Prisma/Go 使用各自生态约定名。
| 变量 | 默认 | 说明 |
|---|---|---|
MANAGER_HOST_PORT |
3312 |
映射到容器内 PORT |
XLANGAI_SERVER_HOST_PORT |
8080 |
映射到容器内 XLANGAI_SERVER_PORT |
| 变量 | 默认 | 说明 |
|---|---|---|
NUXT_ENV |
development |
运行环境。development：HTTP 可登录（登录 Cookie 不带 Secure）；production：Cookie 带 Secure，仅 HTTPS 可登录 |
| 变量 | 默认 | 说明 |
|---|---|---|
NUXT_MANAGER_DATABASE_AUTO_MIGRATE |
true |
启动时执行 Prisma 迁移 |
NUXT_MANAGER_AUTH_SECRET |
— | 运营后台 JWT 签名密钥（生产必改） |
NUXT_MANAGER_AUTO_SEED |
true |
业务种子数据 |
NUXT_MANAGER_TEST_ACCOUNT_SEED |
false |
联调测试账号（13800138000，密码见启动日志） |
NUXT_MANAGER_ADMIN_USERNAME |
— | 首次运营管理员登录名 |
NUXT_MANAGER_ADMIN_PASSWORD |
— | 明文密码（≥6 位），入库 bcrypt |
NUXT_MANAGER_ADMIN_NICKNAME |
管理员 |
管理员昵称 |
NUXT_MANAGER_ADMIN_SEED |
true |
设为 false 关闭管理员自动初始化 |
| 变量 | 默认 | 说明 |
|---|---|---|
NUXT_PUBLIC_OFFICIAL_HOME_URL |
https://xlangai.com |
官网 / 服务器商店地址 |
| 变量 | 默认 | 说明 |
|---|---|---|
DATABASE_URL |
— | PostgreSQL 连接串；manager 与 Go 共用（Prisma 约定） |
AUDIO_DIR |
/app/storage/audio |
manager 与 Go 共用音频目录 |
AVATAR_DIR |
/app/storage/avatars |
用户头像（Go） |
BUNDLED_AUDIO_DIR |
/app/bootstrap-storage/audio |
内置试听音频（Go fallback） |
Go API 内置统一缓存工具（server/internal/cache）：已配置且可连通的 REDIS_URL 时使用 Redis，否则自动降级为进程内内存（单实例开发可用）。
| 变量 | 默认 | 说明 |
|---|---|---|
REDIS_URL |
— | Redis 连接串（见下方示例）；留空则使用内存缓存 |
LANG_CACHE_TTL_SEC |
300 |
语种列表缓存 TTL（秒） |
PRINCIPAL_CACHE_TTL_SEC |
60 |
用户会员 Principal 缓存 TTL（秒） |
多实例部署（水平扩展多个 Go API 副本）务必配置
REDIS_URL，否则 OTP、Principal 等缓存各实例互不共享。
REDIS_URL 使用标准 Redis URI（go-redis ParseURL），密码写在 URL 里即可：
# 无密码
REDIS_URL=redis://127.0.0.1:6379/0
# 仅密码（常见 requirepass）
REDIS_URL=redis://:your-password@127.0.0.1:6379/0
# Redis 6+ ACL（用户名 + 密码）
REDIS_URL=redis://default:your-password@127.0.0.1:6379/0
# TLS（云厂商常用 rediss://）
REDIS_URL=rediss://:your-password@your-redis.example.com:6379/0密码含 @、#、/ 等特殊字符时需 URL 编码（例如 @ → %40）。
若只写 127.0.0.1:6379（不带 redis:// 前缀），当前实现不会解析密码，请改用完整 URI。
- 在 Compose 或
docker/.env中同时设置NUXT_MANAGER_ADMIN_USERNAME与NUXT_MANAGER_ADMIN_PASSWORD。 - 配置
NUXT_MANAGER_AUTH_SECRET。 - 首次启动后使用上述账号登录 http://localhost:3312。
- 初始化完成后：设置
NUXT_MANAGER_ADMIN_SEED=false，并移除NUXT_MANAGER_ADMIN_PASSWORD环境变量。
未配置管理员时不会自动生成随机密码，需自行创建。
- 确认
DATABASE_URL指向生产数据库，且数据库只允许可信网络访问。 - 替换
JWT_SECRET与NUXT_MANAGER_AUTH_SECRET，不要使用镜像默认值。 - 首次管理员初始化完成后，关闭
NUXT_MANAGER_ADMIN_SEED并移除NUXT_MANAGER_ADMIN_PASSWORD。 - 将
NUXT_MANAGER_TEST_ACCOUNT_SEED保持为false，避免创建联调测试账号。 - 为运营后台和 API 配置 HTTPS；如暴露在公网，建议在反向代理层增加访问控制与限流。
- 公网 HTTPS 部署时将
NUXT_ENV设为production；内网或纯 HTTP 访问保持development。 - 将
storage/挂载到持久卷，并纳入备份策略。
- 切勿将生产
JWT_SECRET、服务商 API Key、管理员密码写入镜像或提交版本库。 - 生产务必修改默认密钥，并关闭
NUXT_MANAGER_TEST_ACCOUNT_SEED。
欢迎 Issue 与 Pull Request。提交前请：
- 在本地分别验证
server与manager可正常启动； - 若修改数据库结构，请自行运行
prisma migrate dev并附带 migration 文件； - 勿提交
.env、密钥与storage/用户数据。
推送语义化 tag（如 v0.0.2）后，GitHub Actions 会构建多平台镜像并推送到 Docker Hub（dingdangdog/xlangai），同时创建 GitHub Release。生产服务器将 docker/update.sh 与 docker-compose.yml 放在同一目录，执行 docker/start.sh 即可注册定时任务并轮询 Release 自动滚动部署。
start.sh / update.sh 不是常驻进程；start.sh 会向 crontab 写入每 10 分钟执行一次的 update.sh。要停止自动检查与升级，删除该 crontab 条目即可（将路径换成你服务器上 update.sh 的实际路径）：
crontab -l
crontab -l | grep -v '/path/to/update.sh' | crontab -
crontab -l # 确认已无 update.sh 相关行停掉定时任务不会停止 Docker 容器。若需停止 XLangAI 服务，在 compose 目录执行
docker compose down（数据卷默认保留）。
更完整的 CI/CD 说明见 docs/servers-cicd.md。
本项目采用 MIT License 开源。
Copyright © 2026 GT, DingDangDog