Idoluna / 小P 虚拟偶像直播间

中文 | English

Live demo: https://www.idoluna.cn

中文

Idoluna 是一个虚拟偶像直播间原型。它把 React 前端、Live2D 舞台、弹幕互动、礼物/关注按钮、管理台和 FastAPI 后端放在一起，用来验证“虚拟主播 + 聊天代理 + 直播间状态管理”的最小可用体验。

当前线上版本已接入 OpenAI-compatible 模型接口，部署配置使用 DeepSeek deepseek-v4-pro。如果没有配置模型密钥，后端会退回到本地模板回复。

已实现功能

• 直播间首页：包含 Live2D 舞台区域、弹幕列表、礼物按钮、关注/点赞/分享按钮和直播状态面板。
• 聊天接口：前端弹幕会发送到 FastAPI 后端，后端返回角色回复、情绪、动作和生成来源。
• 模型接入：支持 OpenAI-compatible API，通过环境变量配置 OPENAI_API_KEY、OPENAI_BASE_URL 和 LLM_MODEL_ID。
• 本地兜底：模型不可用或未配置时，使用本地模板保证页面仍可交互。
• 管理台入口：提供直播状态、内容项、广播和 trace 数据的基础管理视图。
• 数据存储：使用 SQLite 保存聊天历史、记忆、知识片段、直播间状态和 trace。
• 部署配置：提供 Dockerfile、Docker Compose 和 Caddy 配置，支持 HTTPS 反向代理。

当前限制

• 这是原型项目，不是完整的商用直播平台。
• Live2D 渲染依赖浏览器 WebGL；不支持 WebGL 的环境会显示舞台占位。
• 语音合成和语音输入需要额外的 TTS/ASR 密钥；默认部署中语音合成是关闭的。
• 没有用户账号体系、支付系统、审核系统或多主播后台。
• 大模型密钥只应放在本地 .env、服务器 .env 或 GitHub Secrets 中，不应提交到仓库。

本地运行

cd /Users/icathia/Desktop/idol
./run.sh

打开 http://127.0.0.1:8000。

./run.sh 会创建后端虚拟环境、安装依赖、安装前端包、构建前端，并启动 FastAPI 服务。

环境变量

可以把变量放在项目根目录 .env、backend/.env，或者 shell 环境中。

USE_OPENAI=true
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.deepseek.com
LLM_MODEL_ID=deepseek-v4-pro

TTS_ENABLED=false
AGENT_RUNTIME_ENABLED=true
CHAT_HISTORY_DB_PATH=data/chat_history.sqlite3
LONG_TERM_MEMORY_DB_PATH=data/agent_memory.sqlite3
KNOWLEDGE_DB_PATH=data/knowledge.sqlite3

Docker 部署

cp .env.example .env
# 填写 OPENAI_API_KEY 等私有配置
docker compose up -d --build

Caddy 会把 80/443 反向代理到后端应用。生产部署时请确认云服务器安全组已放行 TCP 80 和 443。

English

Idoluna is a virtual idol live-room prototype. It combines a React frontend, a Live2D stage area, chat interactions, gift/follow controls, an admin console, and a FastAPI backend to test a minimal “virtual host + chat agent + live-room state” experience.

The current deployment uses an OpenAI-compatible model configuration with DeepSeek deepseek-v4-pro. If model credentials are missing or unavailable, the backend falls back to local template responses.

Implemented

• Live-room UI with a stage area, chat panel, gift controls, like/follow/share actions, and status panels.
• FastAPI chat endpoint that returns character replies, emotion/action metadata, and generation source.
• OpenAI-compatible model support through OPENAI_API_KEY, OPENAI_BASE_URL, and LLM_MODEL_ID.
• Local fallback responses when model credentials are missing or model calls fail.
• Basic admin console for live-room state, content items, broadcasts, and trace data.
• SQLite-backed chat history, memory, knowledge, live-room state, and trace storage.
• Docker Compose and Caddy configuration for deployment behind HTTP/HTTPS.

Limits

• This is a prototype, not a full commercial streaming platform.
• Live2D rendering depends on browser WebGL; unsupported environments show a stage placeholder.
• TTS/ASR requires separate audio service credentials and is disabled by default in deployment.
• There is no account system, payment flow, moderation system, or multi-host operations backend.
• Model keys must stay in local .env files, server .env files, or GitHub Secrets; do not commit secrets.