Twilight 暮光

面向 Emby / Jellyfin 的用户、邀请、卡码、Bot 与运维管理面板。

文档中心 · 安装部署 · Docker 部署 · Telegram 频道 · Telegram 群组

项目定位

Twilight 是一个 Go 后端 + Next.js 前端的 Emby / Jellyfin 用户管理系统，适合需要注册审核、卡码续期、邀请关系、Telegram Bot 绑定、设备/IP 审查和后台运维能力的媒体服务器站点。

当前主线架构：

• 后端：Go，入口为 cmd/twilight，部署目标为 Linux + systemd，也支持 Docker。
• 前端：Next.js App Router、TypeScript、Tailwind CSS、Radix/shadcn 风格组件。
• 存储：单一状态文档模型，支持 JSON 文件或 PostgreSQL；PostgreSQL 下业务状态仍在 twilight_state 单行 jsonb 中，只有会话与运行日志使用独立表。
• 配置：统一读取 config.toml、config.local.toml 与 TWILIGHT_* 环境变量覆盖。

核心能力

快速开始

Docker Compose

git clone https://github.com/Prejudice-Studio/Twilight.git
cd Twilight
cp deploy/docker/config.docker.toml config.toml
cp deploy/docker/.env.example .env

# 编辑 .env，修改 PostgreSQL 密码、内部密钥等部署项
docker compose up -d --build

# 默认访问
# WebUI: http://localhost:3000
# API:   默认仅在 Docker 网络内开放，由 WebUI 代理访问

首次初始化前，在 config.toml 任意结构块中临时写入 setup_mode = true 或 SetupMode = true，再打开 WebUI。若系统没有用户且没有管理员配置，会进入初始化向导。向导会创建首个管理员、写入 [Admin].usernames 与基础配置；Emby、Telegram 和邮箱等非必要项可以跳过，稍后在对应管理页继续完善。完成后初始化标记会从主配置中移除，入口会永久关闭。

完整说明见 Docker 部署。

Linux / systemd

生产部署建议使用 Linux + systemd + Nginx / HTTPS + PostgreSQL：

go build -o bin/twilight ./cmd/twilight
sudo bash deploy/setup-systemd.sh --dry-run
sudo bash deploy/setup-systemd.sh

完整流程见 安装部署。

本地开发

后端：

gofmt -w ./cmd ./internal
go test ./...
go build -o bin/twilight ./cmd/twilight
go run ./cmd/twilight api --host 0.0.0.0 --port 5000 --config config.toml --debug

前端：

cd webui
pnpm install --frozen-lockfile
pnpm dev
pnpm lint
pnpm build

更多约定见 开发指南 与 模块化架构与解耦指南。

文档导航

安全提示

开发者模式

开发者模式通过仪表盘输入 DEBUGMODE 并二次验证管理员密码开启；再次输入 DEBUGMODE 可关闭。关闭后已保存的 JS 预设和 Telegram 指令配置会保留，但所有 js: / js:preset:<id> 指令及相关 JS 交互会被服务端阻断。JS 沙箱使用 Goja，提供受控 users.*、db.*、interactions.*、exit()、assert()、受限 fetch() 和风险提示；不会暴露原始数据库、敏感配置、Token、密码、Telegram ID 或 Emby ID。完整接口见 开发者 JS 沙箱参考。

• 生产环境请启用 HTTPS，并设置安全的 session cookie。
• 首次部署请在配置文件临时启用 setup_mode = true 后使用网页初始化向导，或直接在配置文件中明确指定管理员；普通首个注册用户不会自动成为管理员。
• Token、密码、API Key、数据库 URL 等敏感信息不要写入公开 issue、日志或截图。
• 配置查看和编辑必须依赖后台 schema 的脱敏逻辑，禁止明文回显 secret。
• 公开接口、验证码、发信、绑定码和卡码检查类接口应配置合理限流。

贡献

提交前建议至少执行：

gofmt -w ./cmd ./internal
go test ./...
cd webui && pnpm lint && pnpm build

涉及架构、权限、配置、审计、缓存或外部副作用的改动，请先阅读 模块化架构与解耦指南。

鸣谢

• Emby
• Jellyfin
• TMDB
• Bangumi 番组计划
• Next.js
• Sakura_embyboss
• Bangumi-syncer

贡献者

Star

如果 Twilight 对你有帮助，欢迎点一个 Star。

Made by Prejudice Studio