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 风格组件。
• 存储：唯一运行后端为 PostgreSQL；主要业务状态保存在 twilight_state 单行 JSONB，操作审计、运行日志、会话、播放记录、Telegram 花名册与轮询游标使用独立表以降低高频写放大和常驻内存。JSON 仅用于备份导出和旧数据导入。
• 配置：统一读取 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 typecheck
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 typecheck && pnpm build

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

许可证与二次开发

当前版本采用 GNU AGPL v3 或更高版本，并受 NOTICE 中依据 GNU AGPL 第 7(b) 条声明的署名保留条款约束：

• 允许个人或企业修改、销售、收费部署、提供商业托管与技术支持。
• 分发原版或修改版时，必须继续使用 GNU AGPL，并提供完整的对应源代码。
• 通过网络向用户提供修改版服务时，必须为这些用户提供该运行版本的完整对应源代码。
• 必须保留 Twilight 原始项目名、Prejudice Studio 版权署名、GNU AGPL 许可证，以及上游开源地址 https://github.com/Prejudice-Studio/Twilight。
• 可以增加改版名称、改版作者和改版仓库地址，但不得删除、隐藏、替换或冒充上述原始署名与上游地址，也不得将修改版闭源。

法律文本以 LICENSE 和 NOTICE 为准。详细说明见 许可证与二次开发。已经在旧 MIT 许可证下公开的历史版本不受本次换证追溯影响，历史许可证文本保留于 LICENSES/MIT-legacy.txt。

鸣谢

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

贡献者

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

Made by Prejudice Studio