Elizabeth 是一个以房间为中心的实时文件共享与协作平台：访问一个网址即可建房入职，消息、文件、链接在同一空间即时同步，权限、身份码与文件保护均可按房间独立治理。
它采用 Rust + Next.js 技术栈构建，单容器即可交付 API、WebSocket 与嵌入式 SPA 前端；默认使用 SQLite，也可按需切换到 PostgreSQL。
房间主界面：左侧身份与常用配置、中部实时消息、右侧文件管理，三栏各司其职。
房间驱动的实时文件共享与协作平台，聚合消息、上传、预览、权限与分享链接于同一工作流。
- 零步骤建房，房间即身份：访问
/房间名即自动创建房间并进入，首位创建者自动获得 admin 身份码；无需注册，一个身份码就是一个房间内的角色凭证。 - 三级角色 × 细粒度能力：内置 admin / editor / reader 三种系统角色，映射到
17 项能力（capability），每项能力支持
any/own两种作用域；admin 还可以在"成员与权限"对话框中调整系统角色或新建自定义角色，变更对所有成员实时生效。 - 身份码全生命周期治理：admin 生成 editor / reader 身份码并分发给信任的人；成员可兑换身份码、admin 可轮换自己的凭证、吊销任意会话（对方立即断线）；editor 席位上限 10 个，吊销或过期自动释放。
- 消息与文件的显示 / 隐藏：拥有
msg.visibility.manage/file.visibility.manage能力的角色可以隐藏任意（或仅自己的）消息与文件；被隐藏的内容对无权限者完全不可见，直接访问返回 404，实时推送中也不会泄露正文。 - 文件保护与下载策略：拥有
file.policy.manage能力的身份可为单个文件设置下载保护——无限制、固定访问码或一次性访问码，并可限制总下载次数；访问码支持随机/批量/自定义生成与导出。 - 实时消息与富预览：Markdown 渲染、代码高亮、图片预览、PDF 阅读器、文本查看与链接预览开箱即用；增删改通过 WebSocket 秒级同步给房间内所有人。
- 单容器、单端口交付：Rust 后端统一承载 API、WebSocket
与嵌入式前端静态资源，一条
docker run即可部署。 - SQLite 默认，PostgreSQL 可切换：开发期使用轻量 SQLite，生产环境通过
DATABASE_URL平滑切换，migrations 自动选择执行。 - OpenAPI / Scalar 开箱即用：自带交互式 API 文档，便于二次集成、联调与自动化。
| 成员与权限（身份码分发与会话治理） | 成员与权限（角色能力矩阵） |
|---|---|
 |
 |
| editor 视角（可编辑消息，无 admin 配置区） | 首页（无需注册，创建 / 加入房间） |
|---|---|
 |
 |
Tip
English screenshots are embedded in the English README.
| 文档 | 内容 |
|---|---|
| Docker 快速开始 | 最快把 Elizabeth 跑起来的单机部署路径 |
| 部署指南 | 生产环境部署、反向代理与上线前准备 |
| API 指南 | 核心 REST API、鉴权与内容接口概览 |
| WebSocket 指南 | 实时同步与信令传输入口 |
| 架构说明 | 后端、前端与存储层的整体设计 |
Elizabeth 以 room 为隔离单位：每个房间拥有独立的角色矩阵、身份码会话与文件策略。
| 角色 | 定位 | 默认能力（摘要） |
|---|---|---|
| admin | 房间创建者 / 治理者 | 全部 17 项能力：房间分享与配置、角色管理、身份码签发与吊销、消息与文件的完整操作、下载策略、显隐控制、关闭房间 |
| editor | 受信任的协作者 | 发送 / 编辑消息、上传 / 预览 / 下载文件；删除与显隐仅限自己发布的内容（own 作用域） |
| reader | 只读访客 | 查看与复制消息、预览与下载文件（受下载策略约束） |
每项能力都可单独配置为 any（全部内容）或
own（仅自己创建的内容），也可以新建自定义角色承载更精确的授权组合。
- 生成：admin 在"成员与权限 → 成员身份码"中为 editor 签发身份码（席位上限 10），有效时长可按秒 / 分钟 / 小时 / 天 / 个月配置，到期自动失效且不会超过房间有效期。admin 身份码跟随房间生命周期（可在身份卡上一键轮换），创建房间的第一位用户即持有它。
- 分发：通过任意渠道把身份码交给目标用户。
- 兑换：接收者在房间内粘贴身份码即可获得对应角色，无需注册。
- 轮换：admin 可随时更换自己的 admin 身份码，旧码立即失效。
- 吊销：任意活跃会话可被吊销，对方连接立即断开；席位自动释放。
角色或角色能力变更后，在线成员的能力快照会实时刷新，无需重新登录。
- 下载策略（
file.policy.manage）：按文件独立配置——无限制（Off）/ 固定访问码（Reusable）/ 一次性访问码（One Time），并可限制总下载次数；访问码支持随机、批量、自定义（如VIP666）、去重与导出.txt。受保护文件需输入访问码解锁预览与下载，连续失败会被临时锁定。 - 显示 / 隐藏（
msg.visibility.manage/file.visibility.manage）：隐藏后的内容从无权限用户的列表与实时推送中消失，直接访问返回 404（不泄漏存在性）；own作用域的角色只能隐藏 / 恢复自己发布的内容。
Elizabeth 的正式镜像发布在
Docker Hub yunique001/elizabeth，支持
linux/amd64 与 linux/arm64。默认使用 SQLite；需要 PostgreSQL
时可以直接叠加仓库提供的 Compose override。
| 部署方式 | 是否需要克隆仓库 | 是否在本机构建 | 持久化方式 | 适合场景 |
|---|---|---|---|---|
Docker Hub + docker run |
否 | 否 | Docker named volumes | 最快体验、单机或反向代理部署 |
| Docker Hub + Docker Compose | 是 | 否 | 默认使用宿主机目录 | 易维护、可配置的长期部署 |
Docker Compose / docker build |
是 | 是 | 默认使用宿主机目录 | 开发分支、定制镜像 |
| Rust + Bun 原生构建 | 是 | 是 | 使用本机配置 | 本地开发与调试 |
生产部署推荐固定精确版本，避免 latest 在重建容器时发生非预期升级。下面的版本由
release-please 在 Release PR 中自动更新。
export ELIZABETH_VERSION=2.0.2手动拉取镜像：
docker pull "yunique001/elizabeth:${ELIZABETH_VERSION}"如果只是临时体验，也可以拉取
yunique001/elizabeth:latest；长期部署仍建议使用精确版本。
镜像已经包含 Rust 服务、嵌入式 Web 前端、数据库 migrations、默认 YAML 配置和健康检查，无需克隆仓库。先生成并保存一个稳定的 JWT 密钥：
umask 077
printf 'JWT_SECRET=%s\n' "$(openssl rand -hex 32)" > .env.elizabeth # pragma: allowlist secret然后运行容器：
docker run -d \
--name elizabeth \
--restart unless-stopped \
--init \
--read-only \
--security-opt no-new-privileges:true \
--cap-drop ALL \
--tmpfs /tmp \
-p 127.0.0.1:4092:4092 \
--env-file .env.elizabeth \
-v elizabeth-data:/app/data \
-v elizabeth-storage:/app/storage \
"yunique001/elizabeth:${ELIZABETH_VERSION}"Important
请安全保存 .env.elizabeth，并在重建或升级容器时复用同一个
JWT_SECRET。重新生成密钥会让已有 token 全部失效；不要把该文件提交到版本库。
Note
运行镜像基于 distroless，不含 shell 与 curl，因此健康检查由镜像内置的
HEALTHCHECK 完成（exec 形式调用 /app/board health）。不要改用
--health-cmd：Docker CLI 总会把它的参数包进 /bin/sh -c，而该镜像没有
/bin/sh。这里使用 named volume，Docker 会用镜像内 /app/data、
/app/storage 的内容与属主（uid/gid 65532）初始化它们，无需额外授权；若改为
bind mount，见下方 Compose 方式的目录属主说明。
该命令默认只监听本机 127.0.0.1:4092，适合在前面配置 HTTPS
反向代理。需要直接提供给局域网访问时，可改为 -p 4092:4092；不建议将未启用 TLS
的 HTTP 端口直接暴露到公网。
Compose 方式会复用仓库中的 .env.docker、YAML 配置、数据目录准备脚本和
PostgreSQL override。以下命令只拉取 Docker Hub 镜像，不在本机编译：
git clone --branch "v${ELIZABETH_VERSION}" --depth 1 \
https://github.com/YuniqueUnic/elizabeth.git
cd elizabeth
cp .env.docker .env
${EDITOR:-nano} .env
./scripts/docker_prepare_volumes.sh
docker compose pull backend
docker compose up -d --no-build生产环境必须修改 .env 中的
JWT_SECRET。如果需要选择其他已发布版本，可以在当前 shell 中设置
ELIZABETH_IMAGE=yunique001/elizabeth:<version> 后再执行 Compose 命令。
Note
镜像以 distroless 的 nonroot（uid/gid 65532）运行，没有 shell 也没有
curl。Compose 使用 bind mount，而 Linux 上 bind mount 保留宿主机属主，因此
./scripts/docker_prepare_volumes.sh 会把 docker/backend/data 与
docker/backend/storage 交给 65532:65532 （需要 sudo）；Docker
Desktop（macOS / Windows）会虚拟化属主，脚本自动跳过。健康检查由镜像内置的
HEALTHCHECK 完成，不要改用 --health-cmd——Docker CLI 总会把参数包进
/bin/sh -c，而该镜像没有 /bin/sh。
使用 Compose 构建当前 checkout，并用本地镜像名避免覆盖 Docker Hub 官方镜像的本地 tag：
git clone https://github.com/YuniqueUnic/elizabeth.git
cd elizabeth
cp .env.docker .env
${EDITOR:-nano} .env
./scripts/docker_prepare_volumes.sh
ELIZABETH_IMAGE=elizabeth:local docker compose up -d --build也可以只构建镜像，再复用"方式一"的 docker run 参数：
docker build \
--target runtime \
-f Dockerfile.backend \
-t elizabeth:local \
.本地需要安装仓库指定的 Rust toolchain、Bun，以及可选的
just。推荐直接运行：
cd web
bun install --frozen-lockfile
bun run build:embedded
cd ..
ELIZABETH_SKIP_WEB_BUILD=1 cargo build --release -p elizabeth-board构建产物位于 target/release/board。本地开发可使用 just dev；完整 release
构建可使用 just build。
Elizabeth 根据 DATABASE_URL 的协议自动选择 SQLite 或 PostgreSQL migrations。
使用仓库提供的 PostgreSQL 容器时，先在 .env 中设置安全的
POSTGRES_PASSWORD，再运行：
docker compose \
-f docker-compose.yml \
-f docker-compose.postgres.yml \
pull
docker compose \
-f docker-compose.yml \
-f docker-compose.postgres.yml \
up -d --no-build如果需要从当前源码构建，将最后一条命令的 --no-build 替换为 --build，并设置
ELIZABETH_IMAGE=elizabeth:local。
使用外部 PostgreSQL 时，在 .env 中设置连接串，并确保后端容器可以访问目标主机：
DATABASE_URL=postgresql://用户名:密码@主机名:端口/数据库名 # pragma: allowlist secret容器内关键路径：
| 路径 | 内容 | 是否必须持久化 |
|---|---|---|
/app/data |
SQLite 数据库 | 使用 SQLite 时必须 |
/app/storage |
房间上传文件 | 必须 |
/app/config/backend.yaml |
部署级默认配置、房间策略与 middleware 配置 | 可使用镜像内置版本或只读挂载 |
docker run 示例使用 named volumes；Compose 默认将它们绑定到
./docker/backend/data、./docker/backend/storage 和
./docker/backend/config/backend.yaml，也可以通过 .env 中的
ELIZABETH_DATA_DIR、ELIZABETH_STORAGE_DIR、ELIZABETH_BACKEND_CONFIG 覆盖。
常用环境变量：
| 环境变量 | 默认值 | 作用说明 |
|---|---|---|
JWT_SECRET |
示例值，仅供启动 | 签名认证令牌；生产环境必须设置稳定的 32+ 字符密钥 |
DATABASE_URL |
sqlite:///app/data/elizabeth.db |
数据库连接串，协议决定驱动和 migrations |
BACKEND_PORT |
4092 |
Compose 暴露到宿主机的端口 |
ELIZABETH_ADMIN_USERNAME / _PASSWORD |
空（管理面板关闭） | 首次启动时创建平台管理员；之后改密走 /admin 面板 |
LOG_LEVEL / RUST_LOG |
info |
日志级别；RUST_LOG 支持按模块指令，并优先于前者 |
ROOM_MAX_SIZE |
50MiB |
新房间默认容量，支持 50M、100M、1G、1GiB |
ROOM_MAX_TIMES_ENTERED |
100 |
新房间默认最大进入次数 |
ROOM_ALLOWED_AGES |
1m,30m,2h,12h,1d,7d,30d,365d |
前端可选、后端接受的房间期限，必须严格升序 |
ROOM_DEFAULT_AGE |
2h |
新房间默认过期时间，必须包含在 ROOM_ALLOWED_AGES 中 |
ROOM_DEFAULT_PASSWORD |
空 | 新房间默认密码；空值表示无密码 |
ROOM_DEFAULT_ROLE |
reader |
新房间默认加入角色：admin / editor / reader |
ROOM_SHARE_DISABLED_LOCK_DURATION |
1h |
关闭分享后的锁定时长，支持 humantime 单位 |
STORAGE_BACKEND / STORAGE_TRANSFER |
fs / proxy |
内容存放位置与传输方式；s3 + presigned 走对象存储直传 |
STORAGE_S3_ENDPOINT 等 STORAGE_S3_* |
空 | STORAGE_BACKEND=s3 时的 endpoint、bucket 与凭据 |
MIDDLEWARE_SECURITY_DISALLOW_SEARCH_INDEXING |
true |
服务 Disallow: / 的 robots.txt，并给 HTML 加 noindex |
后端支持的全部环境变量、分组说明与各自的内置默认值见仓库根目录的 .env.docker，
docker-compose.yml 会把其中每一项透传给容器。
镜像内置配置位于 /app/config/backend.yaml，仓库模板位于
docker/backend/config/backend.yaml。YAML 不执行 ${VAR}
插值；容器环境变量会在启动时覆盖对应 YAML 值。
部署成功后可访问：
- Web：
http://localhost:4092/ - 健康检查：
http://localhost:4092/api/v1/health - Scalar API 文档：
http://localhost:4092/api/v1/scalar - OpenAPI JSON：
http://localhost:4092/api/v1/openapi.json
常用 Compose 命令：
docker compose ps
docker compose logs -f backend
curl -fsS http://127.0.0.1:4092/api/v1/health
docker compose down --remove-orphans升级预构建镜像时，先切换到目标 release，再拉取并重建容器：
docker compose pull backend
docker compose up -d --no-build --remove-orphans直接使用 docker run 的部署，应先拉取新版本、删除旧容器，再使用相同的
.env.elizabeth、端口和 elizabeth-data / elizabeth-storage volumes
重新执行启动命令。升级或停止容器时不要删除数据卷。
just dev # 构建嵌入式前端并启动本地服务（默认端口 4092）参与 Rust 模块开发时，必须确保以下质量门禁全部通过：
cargo fmt --all
cargo check --workspace --all-targets --all-features
cargo test --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warningsTip
如果本地装有 just，也可以直接使用
just verify 一键跑通上述所有校验。
cd web
bun install --frozen-lockfile
bun run dev # 开发服务器（代理 /api 到本地后端）
bun run typecheck # tsc --noEmit
bun run lint # eslint --max-warnings 0web/e2e 下维护了一套 Screenplay 模式的 e2e 套件，覆盖权限边界（越权写入、绕过
下载策略、吊销即断线、editor 席位上限）、显隐能力、实时协同与关键交互流，不只测
happy path：
cd web
bun run e2e:test # 运行整套 e2e（自动拉起隔离的测试后端）
bun run e2e:report # 生成并查看 Serenity 报告若要探索和深入了解 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)
开源许可证托管，完整协议文本见仓库根目录的 LICENSE。
Copyright (C) 2026 unic <yuniqueunic@gmail.com>
Important
AGPL-3.0 协议与商业授权说明：
- 任何人均有权自由地商用、修改或分发本项目的全部或部分源代码。
- 开源义务：如果您对本项目的源代码进行了任何修改，并且利用修改后的源码通过网络以软件即服务（SaaS）的形式向公众提供服务，您必须根据 AGPL-3.0 的条款向公众开源并公布修改后的完整源代码。
- 如果您没有对 Elizabeth 的源代码进行任何修改（仅作为直接部署使用者进行商业运营、团队协作或个人自建），或者您的修改仅限在企业/个人内部私有环境使用且不对外提供网络服务，则您无需公开任何源代码。