Elizabeth 是一个以房间为中心的实时文件共享与协作平台：在同一个入口里完成建房、消息同步、拖拽上传、图片 / PDF / 文本预览，以及链接邀请分享。
它采用 Rust + Next.js 技术栈构建，单容器即可交付 API、WebSocket 与嵌入式 SPA 前端；默认使用 SQLite，也可按需切换到 PostgreSQL。
房间驱动的实时文件共享与协作平台，聚合消息、上传、预览与分享链接于同一工作流。
- Docker 快速开始：最快把 Elizabeth 跑起来的单机部署路径。
- 部署指南：生产环境部署、反向代理与上线前准备。
- API 指南：核心 REST API、鉴权与内容接口概览。
- WebSocket 指南：实时同步与信令传输入口。
- 架构说明：后端、前端与存储层的整体设计。
- Room-centric 协作模型：所有消息、文件与实时互动都围绕房间展开，分享路径直接、上手成本低。
- 单容器、单端口交付：Rust 后端统一承载 API、WebSocket 与嵌入式前端静态资源，部署链路简单清晰。
- 实时消息与多类型预览：支持 Markdown、代码高亮、图片预览、PDF 阅读器、文本文件查看与链接预览。
- SQLite 默认，PostgreSQL 可切换：开发期可用轻量 SQLite，生产环境可通过
DATABASE_URL平滑切换至 PostgreSQL。 - OpenAPI / Scalar 开箱即用：自带交互式 API 文档，便于二次集成、联调与自动化。
- 安全基线完整：内置 JWT 鉴权、房间权限控制与最小权限容器运行策略。
一键拉取并部署项目（默认搭载轻量级 SQLite 数据库驱动）：
# 克隆仓库
git clone https://github.com/YuniqueUnic/elizabeth.git
cd elizabeth
# 准备环境变量配置文件
cp .env.docker .env
# 生产环境务必修改 JWT_SECRET（推荐长度 >= 32 字符的随机安全字符串）
${EDITOR:-nano} .env
# 一键构建并拉起服务
docker compose up -d --build部署成功后，您可以通过以下入口访问和调试服务：
- Web 前端界面：
http://localhost:4092 - Scalar 交互式接口文档：
http://localhost:4092/api/v1/scalar - OpenAPI 描述文件 (JSON)：
http://localhost:4092/api/v1/openapi.json - 健康检查接口：
http://localhost:4092/api/v1/health
Elizabeth 依靠 sqlx::AnyPool 具备出色的数据库自适应能力，能够根据 .env
中传入的 DATABASE_URL
的协议头自动决策装载哪套驱动，且在迁移（Migrations）上实现了智能切换：
- 轻量级 SQLite（默认，使用
./crates/board/migrations/ 容器内/app/migrations） - 生产级 PostgreSQL（使用
./crates/board/migrations_pg/ 容器内/app/migrations_pg）
如果您希望配合内置的 PostgreSQL 容器一同拉起服务，只需运行：
docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d --build如果您有独立部署的外部 PostgreSQL 数据库，请在 .env 中修改连接串（确保后端
Docker 容器具有网络访问权限）：
DATABASE_URL=postgresql://用户名:密码@主机名:端口/数据库名 # pragma: allowlist secret在 Docker 容器化环境下，推荐通过项目根目录的 .env
环境变量配置文件覆盖核心行为：
| 环境变量 | 默认值 | 作用说明 |
|---|---|---|
JWT_SECRET |
（必填） | 用于生成和签名认证令牌的秘钥。生产环境请务必修改。 |
DATABASE_URL |
sqlite:///app/data/elizabeth.db |
数据库连接串。协议头决定了使用的驱动类型。 |
DB_MAX_CONNECTIONS |
20 |
数据库连接池的最大连接数上限。 |
DB_MIN_CONNECTIONS |
5 |
数据库连接池保留的最小连接数常驻。 |
Note
项目的静态配置文件位于
docker/backend/config/backend.yaml，该文件在运行时加载（注：YAML
自身不支持动态读取环境变量，密钥和高敏感配置均推荐使用 env 注入来覆盖）。
在本地参与 Rust 模块开发时，必须确保以下指令全部正常通过：
# 格式化代码风格
cargo fmt --all
# 静态检查 workspace 语法与编译正确性
cargo check --workspace --all-targets --all-features
# 运行 workspace 内部的所有自动化测试
cargo test --workspace --all-features
# Clippy 强静态类型质量门禁（不能包含任何警告或错误）
cargo clippy --workspace --all-targets --all-features -- -D warningsTip
如果本地装有 just，您也可以直接使用命令
just verify 一键跑通上述所有的校验。
若要探索和深入了解 Elizabeth，请参阅我们为您准备的系统化文档：
- docs/README.md：项目文档导航主索引。
- docs/DOCKER_QUICK_START.md：极简的 Docker 快速上路部署手册。
- docs/DEPLOYMENT.md：生产级环境部署、云服务配置及 Nginx/反向代理的最佳实践。
- docs/API_GUIDE.md：系统底层核心 RESTful API 调用与字段详情说明。
- docs/WEBSOCKET_GUIDE.md：WebSocket 长连接房间状态同步与信令传输协议。
- docs/ARCHITECTURE.md：项目宏观架构设计、多层逻辑解耦与底层技术深度实现。
本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 开源许可证托管。
Important
AGPL-3.0 协议与商业授权说明：
- 任何人均有权自由地商用、修改或分发本项目的全部或部分源代码。
- 开源义务：如果您对本项目的源代码进行了任何修改，并且利用修改后的源码通过网络以软件即服务（SaaS）的形式向公众提供服务，您必须根据 AGPL-3.0 的条款向公众开源并公布修改后的完整源代码。
- 如果您没有对 Elizabeth 的源代码进行任何修改（仅作为直接部署使用者进行商业运营、团队协作或个人自建），或者您的修改仅限在企业/个人内部私有环境使用且不对外提供网络服务，则您无需公开任何源代码。