提灯桌 Lantern Table

面向 3～6 人小型 D&D 团的轻量网络跑团桌。一个实例可以创建多个隔离房间，玩家使用房间号、房间密码和桌边称呼加入，不需要注册账号。

当前版本：v0.9.4

主要功能

• 四套具有独立布局和动效的主题：烛火羊皮、冒险者作战桌、秘法观星台、地下城档案库
• 正方形网格地图，支持导入 PNG、JPG、WebP，缩放、平移、锁定和队伍定位
• 可导入图片的棋子，自动吸附网格，支持 1×1、2×2、3×3 占格
• DM 战争迷雾框选、共享画笔、测距、信标和场景管理
• 可编辑角色档案、资源、状态、常用动作、头像与棋子
• 可编辑怪物 HP、上限 HP、AC、先攻、快捷命中和伤害骰
• 持久化先攻与战斗轮次，玩家结束自己的回合，DM 推进或重置战斗
• 目标、线索、队伍笔记、聊天、优势／劣势与掷骰动画
• 房间密码、独立 DM 密码、玩家设备绑定和登录限流
• SQLite 自动保存、实时同步、完整 JSON 战役包导入导出
• 桌面、平板和手机适配

语音、完整规则库、动态光照和公开组队大厅不在当前版本范围内。

选择部署方式

使用场景	推荐方式	公网地址	电脑要求
自己测试	Windows 本机启动	http://localhost:3000	开团时保持运行
没有服务器，临时线上开团	Windows + Tailscale Funnel	自动生成 https://…ts.net	开团电脑保持开机联网
有长期运行的电脑或服务器	Docker Compose	自备域名或 Tailscale	主机持续运行
不想维护服务器	Cloudflare Workers	自动生成 https://…workers.dev	本地电脑无需保持开机

下载项目

会使用 Git 的用户：

git clone https://github.com/mec2780890986-code/lantern-table.git
cd lantern-table

不使用 Git：打开 GitHub 仓库，点击 Code → Download ZIP，下载后完整解压。不要直接在压缩包预览窗口里运行脚本。

方式一：Windows 本机运行

1. 安装 Node.js

安装 Node.js 24 LTS 或更高版本，然后重新打开项目文件夹。

2. 启动

双击：

启动提灯桌.bat

首次运行需要设置两个不同且至少 6 位的密码：

• 房间密码：发给玩家。
• DM 管理密码：仅由 DM 保存，不要发给玩家。

浏览器会打开：

http://localhost:3000/?room=emberfall

关闭启动窗口会停止服务。Windows 版配置与战役数据保存在：

%LOCALAPPDATA%\LanternTable\data

需要重设默认密码时，先停止服务，再删除该目录中的 server-settings.json。不要删除 lantern-table.db 和 uploads/。

方式二：Windows + Tailscale Funnel 公网开团

适合没有云服务器、只在开团时开放网站的 DM。

1. 安装依赖

• Node.js 24 LTS 或更高版本
• Tailscale for Windows

打开 Tailscale 并登录。登录成功后，设备应出现在 Tailscale Machines 页面。

2. 一键启动

双击：

启动公网提灯桌.bat

启动过程中 Windows 会显示管理员确认。首次使用 Funnel 时，浏览器还会打开一次授权页面。成功后窗口会显示类似地址：

https://your-device.your-tailnet.ts.net/?room=emberfall

把完整链接和房间密码发给玩家。不要分享 DM 密码。电脑必须保持开机、联网，启动窗口也要保持开启。

结束开团时回到启动窗口按 Enter。脚本会关闭本次 Funnel 入口并停止它启动的本地服务。

手动检查 Funnel

以管理员身份打开 PowerShell：

tailscale funnel status
tailscale status

如果一键脚本无法建立入口，可以先启动本地服务，再执行：

tailscale funnel --bg 3000

关闭手动创建的全部 Funnel 配置：

tailscale funnel reset

Tailscale Funnel 会自动提供 HTTPS。--bg 创建的配置会在后台保持，并可在设备或 Tailscale 重启后恢复；一键脚本会在你按 Enter 结束开团时主动清理它创建的入口。

方式三：Docker Compose 部署

适合长期运行的家用电脑、NAS、Linux 主机或云服务器。

1. 安装 Docker

• Windows、macOS：安装 Docker Desktop。
• Linux：安装 Docker Engine 和 Docker Compose 插件。

确认命令可用：

docker --version
docker compose version

2. 配置密码

进入项目目录，复制环境变量示例：

Linux/macOS：

cp .env.example .env

Windows PowerShell：

Copy-Item .env.example .env
notepad .env

将 .env 中两个示例值改为不同的长密码。建议至少 16 个字符。.env 已被 Git 忽略，不要手动上传。

3. 检查并启动

docker compose config
docker compose up -d --build
docker compose ps

健康状态变为 healthy 后访问：

http://服务器地址:3000/?room=emberfall

查看日志：

docker compose logs -f --tail=100

停止容器但保留数据：

docker compose down

不要执行 docker compose down -v，除非你明确要永久删除数据库和上传图片。

4. 更新版本

先在页面设置中导出完整战役包，然后执行：

git pull --ff-only
docker compose up -d --build
docker compose ps

Compose 会重建应用容器，命名卷 lantern-data 会继续保存数据库和图片。

5. 公网访问

应用本身监听 HTTP。长期公开时应放在 Caddy、Nginx Proxy Manager 或其他 HTTPS 反向代理后面。也可以在安装了 Tailscale 的宿主机上执行：

tailscale funnel --bg 3000

不要直接把未加密的 3000 端口暴露给整个互联网。

方式四：Cloudflare Workers 部署

这个版本使用 Workers Static Assets 和 Durable Objects。战役状态与图片按房间持久化；图片会被分块保存，因此不需要开通 R2、绑定银行卡，也不需要让本地电脑保持运行。

1. 登录

需要一个启用了 Workers 的 Cloudflare 账号。进入项目目录后执行：

npm install
npm exec wrangler login

2. 设置默认房间密码

分别执行下面两条命令，并按提示输入不同的长密码。建议至少 16 个字符。

npm exec wrangler secret put ROOM_KEY
npm exec wrangler secret put DM_KEY

这两个密码只用于默认房间 emberfall。之后由 DM 在登录窗口创建的新房间使用各自的房间密码和 DM 密码。

3. 部署

npm run cloudflare:deploy

命令结束时会显示 https://lantern-table.<你的子域>.workers.dev。默认房间地址为：

https://lantern-table.<你的子域>.workers.dev/?room=emberfall

本地预览使用：

npm run cloudflare:dev

Cloudflare 版和本机 SQLite 版的数据互不相通。迁移战役时，在旧版本设置中导出完整战役包，再到新版本导入。

Docker 环境变量

变量	必填	默认值	作用
ROOM_KEY	是	无	默认房间密码
DM_KEY	是	无	默认 DM 管理密码
PORT	否	3000	HTTP 监听端口
DATA_DIR	否	项目内 data/	数据库和上传图片目录

新房间由 DM 在进入页面勾选“房间不存在时创建”，并为该房间设置独立的房间密码和 DM 密码。

数据与备份

手动运行时默认数据结构：

data/
├── lantern-table.db
├── server-settings.json
└── uploads/

不同启动方式的数据位置：

• Windows 双击启动：%LOCALAPPDATA%\LanternTable\data
• 手动执行 node server.mjs：项目内 data/
• Docker Compose：命名卷 lantern-data

推荐备份方式是在右上角设置中导出完整 JSON 战役包。导出文件会嵌入当前战役引用的地图、头像和棋子原图，可用于迁移到另一台主机。

房间与权限

• 房间号只接受英文字母、数字、下划线和短横线。
• 玩家只能移动和编辑与自己桌边称呼对应的角色。
• 玩家首次进入后会绑定当前浏览器。换设备或清理浏览器数据后，由 DM 在设置中解除旧绑定。
• DM 可以管理全部棋子、地图、战争迷雾、敌人、目标、线索和战斗轮次。
• 玩家接口不会收到未公开的敌人 HP、AC 和怪物快捷攻击数据。
• 玩家只能在轮到自己时结束回合；DM 可以随时推进下一位或重置战斗。
• 地图视图默认锁定。解锁后可以平移和缩放；棋子拖动时按住 Alt 可临时绕过网格吸附。
• DM 可开放玩家共享画笔。玩家只能撤销自己的最后一条笔迹。

快捷键

• /：聚焦聊天输入框
• R：快速投掷 D20
• E：轮到自己时结束回合
• B：切换地图画笔
• M：切换测距工具
• P：切换地图信标
• F：DM 切换框选迷雾
• Esc：返回选择工具

常见问题

网页打不开

先在运行主机访问 http://127.0.0.1:3000/api/health。正常响应应包含：

{"status":"ok","version":"0.9.4"}

本机健康检查失败时查看启动窗口或 docker compose logs --tail=100。本机正常而公网失败时检查 Funnel、反向代理、防火墙和主机是否仍在线。

Tailscale 登录出现 401 或 cookie 错误

关闭旧登录页，从 Tailscale 托盘菜单退出后重新登录。不要反复刷新已经失效的 OAuth 页面。登录成功后在 Machines 页面确认设备在线，再重新运行公网启动脚本。

玩家换设备后无法使用原称呼

让 DM 打开设置，在“玩家设备绑定”中解除该称呼的旧绑定，然后让玩家重新加入。

图片上传失败

仅支持 PNG、JPG 和 WebP。单张图片上限为 8 MB，每个房间的图片素材上限约为 250 MB。

开发与检查

npm test
npm run dev

健康检查：

GET /api/health

发布前至少运行：

npm test
docker compose config