一个实验室，一个数据库。

桌面版还是服务器？

两种情况下 BioManager 都是同一个程序，区别只在于数据库放在哪里、谁能访问它。

选择方式

回答三个问题就能定下来：

1. 只有你自己用？用桌面版（A）就行了。
2. 所有人都在同一栋楼、同一个网络里？可以用实验室网络里的一台电脑（B）， 或者向 IT 部门申请学校的服务器（C）。
3. 有人在家里、用手机流量，或者分布在不同地点？用配合 Tailscale 的云虚拟机（D）：私密、免费，在哪里都能访问。我们向大多数实验室推荐这种方式。 只有当你想要一个不装任何应用也能打开的普通网址时，才用自己的 域名（E）。

价格是这些服务在 2026 年 9 月的收费，注册前请再核实。 所有服务器方式（B–E）都包含每晚备份、每周恢复测试和 HTTPS。

A · 单台电脑：桌面版

免费 · 2 分钟 · 只属于这台电脑

1. 为你的电脑下载 BioManager：macOS（Apple 芯片或 Intel）、Windows 或 Linux。
2. Mac：解压后把 BioManager 拖到“应用程序”文件夹，第一次打开时右键点按 → 打开 → 打开（right-click → Open → Open）。 Windows：解压 zip，打开 BioManager.exe，出现警告时选择更多信息 → 仍要运行（More info → Run anyway）。 Linux：给 AppImage 加上可执行权限，然后打开。
3. 创建你的账号，回答设置问题。详见用户指南。

你的数据存放在应用之外（Mac 上是 ~/Library/Application Support/Biomanager/， Windows 上是 %APPDATA%\Biomanager\，Linux 上是 ~/.local/share/Biomanager/），所以更新 永远不会动到它。请用 Time Machine 或“文件历史记录”备份这个文件夹，并且千万不要把它放在 Dropbox、 OneDrive、Google Drive 或 iCloud Drive 里：同步会损坏数据库。

同一网络里的几个人不用服务器也能共用一台电脑上的实验室：设置 → 设备 → 在网络上共享这个实验室 （Settings → Devices → Share this lab on the network）会把这台电脑设为实验室的主副本，其他人用它显示的地址打开。 这台电脑必须一直开着，不会像服务器那样每晚备份，而且连接没有加密：在你信任的实验室网络里没问题， 要求更高就用服务器（设备）。

B · 实验室网络里的一台电脑

有闲置电脑就免费 · 1 小时 · 在实验室或校园网络内访问

任何一直开着的电脑都可以当服务器：一台 Linux 电脑、一台旧台式机，或者一台 Mac mini。实验室成员 用类似 https://192.168.1.50 的地址打开它。除非学校的 VPN 能把人接入这个网络， 否则从网络外面访问不到它。

1. 给这台电脑一个固定地址。向 IT 部门申请一个固定 IP 地址或 DNS 名称（例如 biomanager.bio.youruni.edu），让地址不会变。关闭睡眠。
2. 安装 Docker。Linux：运行 curl -fsSL https://get.docker.com | sudo sh，然后运行 sudo usermod -aG docker $USER，再重新登录。Mac：安装 Docker Desktop（教育用途和小型 组织免费）或 OrbStack，并设为登录时启动。
3. 把服务器安装包放到 /opt/biomanager：

   sudo mkdir -p /opt/biomanager && sudo chown "$USER" /opt/biomanager
   curl -fsSL -o /tmp/biomanager-server.tar.gz \
     https://github.com/gaspolymerase/biomanager/releases/latest/download/biomanager-server.tar.gz
   tar -xzf /tmp/biomanager-server.tar.gz -C /opt/biomanager
   cd /opt/biomanager/Biomanager/deploy
   host/load-image.sh                  # downloads the app for this machine (Intel or ARM)
   cp .env.example .env && chmod 600 .env

4. 填写 .env，用文本编辑器打开（nano .env）：

   DOMAIN=192.168.1.50            # or the DNS name IT gave you
   TLS=internal                    # BioManager makes its own certificate
   POSTGRES_PASSWORD=...           # paste the output of: openssl rand -hex 24
   TZ=America/New_York             # your time zone
   BACKUP_DIR=/opt/biomanager/backups   # better: a folder on a second disk

   如果 IT 部门为这个名称提供了证书，就改用 TLS=files，把证书放在 certs/server.crt 和 certs/server.key：这样就可以跳过第 7 步。
5. 启动：

   docker compose up -d
   docker compose logs app | grep "setup code"

6. 创建管理员账号。在服务器本机上打开 https://DOMAIN/register，输入上一步得到的 设置码（setup code）。第一个账号就是实验室的管理员。
7. 在每台设备上信任它的证书，只需一次。先导出证书： docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt > biomanager-root.crt 然后安装这个文件：
   • Mac：双击它，然后在“钥匙串访问”里打开它，把信任 → 始终信任（Trust → Always Trust）选上。
   • Windows：双击 → 安装证书 → 本地计算机 → 受信任的根证书颁发机构（Install Certificate → Local Machine → Trusted Root Certification Authorities）。
   • iPhone/iPad：用隔空投送或邮件发过去，在设置 → 通用 → VPN与设备管理（Settings → General → VPN & Device Management）里安装描述文件，然后在设置 → 通用 → 关于本机 → 证书信任设置（Settings → General → About → Certificate Trust Settings）里打开它。
   • Android：设置 → 安全 → 加密与凭据 → 安装证书 → CA 证书（Settings → Security → Encryption & credentials → Install a certificate → CA certificate）。
8. 让大家能连进来：在这台电脑的防火墙里允许 443 端口的入站连接，然后把地址发给实验室成员。 在 Linux 上，还要安装看门狗和每周自动更新：运行 sudo host/install.sh（在 deploy 文件夹里）。

C · 学校或院系的服务器

通常免费 · 难的部分由 IT 部门完成 · 校园网络和 VPN

很多大学会在校园网络上给实验室提供虚拟机。把下面这段申请发给 IT 部门：

“我们需要一台小型 Linux 虚拟机（Ubuntu 24.04，2 vCPU，4 GB RAM，40 GB 硬盘），装好 Docker， 配一个 DNS 名称，例如 biomanager.ourdept.university.edu，以及这个名称的 TLS 证书，并对校园网络和 VPN 开放 443 端口。它在 Docker 容器里运行 BioManager，一个实验室数据库。”

然后从 B 的第 3 步开始照做，使用 TLS=files，把 IT 部门给的证书放在 certs/ 里。 实验室的设备上什么都不用装。如果 IT 部门提供虚拟机备份，就用上：多一层保护总是好的。

D · 配合 Tailscale 的云虚拟机 推荐

免费 · 大约一小时 · 你的实验室在哪里都能访问，其他人都不能

服务器是云上的一台虚拟机。Tailscale 在你实验室的各台设备之间 建立一个私有网络：服务器在互联网上没有任何开放端口，但实验室成员无论连着哪里的 Wi-Fi 还是手机信号，都能用一个普通的 HTTPS 地址打开它，比如 https://biomanager.tail1234.ts.net， 证书是正规的，不用手动信任任何东西。

1. 账号

1. 注册一个免费的 Oracle Cloud 账号（会要求绑定银行卡 来验证身份；Always Free 资源永远不会收费）。选一个离你近的主区域（home region）：选定后不能更改。
2. 注册一个免费的 Tailscale 账号，可以用实验室或个人的 Google、 Microsoft 或 GitHub 账号登录。
3. 在你自己的电脑上，下载服务器 安装包，解压后用文本编辑器打开 Biomanager/deploy/cloud-init.yaml。下一步要把它粘贴进去。

2. 创建虚拟机

1. 在 Oracle Cloud 里：Compute → Instances → Create instance。
2. Image（镜像）：Canonical Ubuntu 24.04。Shape（规格）：Ampere VM.Standard.A1.Flex，2 OCPU、12 GB （或 4 OCPU、24 GB）。如果 Oracle 提示容量不足，稍后再试，或者换一个可用性域（availability domain）。
3. Networking（网络）：新建一个公共子网，分配一个公网 IPv4 地址（只在第一次 SSH 登录时需要）。
4. SSH keys（SSH 密钥）：上传你的公钥（ssh-keygen -t ed25519 可以生成一对；.pub 文件就是公钥）。
5. Advanced options → Management → Initialization script：粘贴 cloud-init.yaml 的内容。 它会在第一次启动时安装 Docker、Tailscale 和安全更新。
6. 创建后等几分钟。也可以在 Billing 里把账号升级为 Pay As You Go（按量付费）：Always Free 资源仍然免费，而且 Oracle 从此不会回收闲置的免费虚拟机。

3. 接入 Tailscale

ssh ubuntu@<the VM's public IP>
ls /var/lib/biomanager-ready          # exists once first-boot set-up has finished
sudo tailscale up --ssh --hostname=biomanager

打开它输出的链接并登录。然后在 Tailscale 管理控制台里：

• Machines → biomanager → ⋯ → Disable key expiry（关闭密钥过期，否则 180 天后它会掉线）；
• DNS：打开 MagicDNS 和 HTTPS Certificates。记下你的 tailnet 名称，类似 tail1234.ts.net。

从现在起，通过 Tailscale 用 ssh ubuntu@biomanager 连接。

4. 启动 BioManager

curl -fsSL -o /tmp/biomanager-server.tar.gz \
  https://github.com/gaspolymerase/biomanager/releases/latest/download/biomanager-server.tar.gz
tar -xzf /tmp/biomanager-server.tar.gz -C /opt/biomanager
cd /opt/biomanager/Biomanager/deploy
host/load-image.sh                     # downloads the app for this machine (Intel or ARM)
cp .env.example .env && chmod 600 .env
nano .env

DOMAIN=biomanager.tail1234.ts.net     # biomanager + your tailnet name
TLS=tailscale
COMPOSE_FILE=compose.yaml:compose.tailscale.yaml
POSTGRES_PASSWORD=...                  # openssl rand -hex 24
TZ=America/New_York
BACKUP_DIR=/opt/biomanager/backups

docker compose up -d
docker compose ps                      # wait until app and backup say "healthy"
docker compose logs app | grep "setup code"
sudo host/install.sh                   # watchdog, weekly updates and phone alerts

在一台装了 Tailscale 的设备上打开 https://DOMAIN/register，用设置码创建管理员账号。 install.sh 会输出一个 ntfy 主题：在 ntfy 应用里订阅它， 一旦网站、备份或硬盘需要你处理，就会收到通知。

5. 关上门

在 Oracle Cloud 里打开这台虚拟机的子网 → Security list（安全列表），删除 22 端口的入站规则。服务器 现在在互联网上没有任何开放端口；SSH 和网站都走 Tailscale。

6. 邀请实验室成员

1. 每位成员安装 Tailscale，然后要么加入你的 tailnet（Users → Invite），要么（不管多少人都更简单） 由你把服务器单独共享给他们自己的 Tailscale 账号：Machines → biomanager → Share。
2. 他们打开地址，选择创建账号（Create account），你在管理用户（Manage users）里批准。
3. 手机：先打开 Tailscale 应用，然后用 BioManager Android 应用；iPhone 上用 Safari → 添加到主屏幕（Add to Home Screen）。

实验室以外的人如果只需要看几天，不用装 Tailscale：见访客通行码。

E · 用自己域名的云虚拟机

虚拟机同 D + 一个域名（每年大约 $10–15）· 一个任何人都能打开的普通网址

大家不用装任何应用，直接访问 https://biomanager.yourlab.org。这份方便的代价是： 登录页面暴露在公开的互联网上。BioManager 为此做了准备：新注册要等管理员批准，密码输错会被限速， 改密码后已登录的会话会失效，并启用了严格的内容安全策略。但仍然请使用强密码，并考虑用 Google 或 Microsoft 登录。

1. 从 Cloudflare、Porkbun 或 Namecheap 等注册商购买一个域名（或者用院系给你的 子域名）。
2. 按 D 的第 1–2 步创建虚拟机（Tailscale 可装可不装，但它仍是 SSH 登录最安全的方式）。
3. 在注册商那里添加一条 DNS A 记录：biomanager → 虚拟机的公网 IP。
4. 在云防火墙里（Oracle：子网的安全列表）允许来自任何地址的 TCP 80 和 443 入站连接。 Let's Encrypt 签发证书需要用到 80 端口。
5. 按 D 的第 4 步获取安装包并填写 .env，其中：

   DOMAIN=biomanager.yourlab.org
   TLS=acme
   [email protected]       # Let's Encrypt writes here before a certificate expires

   然后运行 docker compose up -d。Caddy 会自动获取并续期证书。
6. 用设置码在 https://biomanager.yourlab.org/register 创建管理员账号，然后运行 sudo host/install.sh（在 deploy 文件夹里）。

其他方式

访客通行码：进来待几天，不用 Tailscale

在 Tailscale 服务器（D）上，管理员可以让实验室以外的人临时进来。在账号菜单的访客（Guests）里 生成一个通行码，然后用 Tailscale Funnel 把服务器开放到互联网： sudo deploy/host/internet-access.sh on（第一次运行时，Tailscale 会输出一个允许 Funnel 的链接）。 访客打开 https://DOMAIN:8443/guest 并输入通行码；其他人在那里只能看到输入通行码的页面。 运行 internet-access.sh off 就会重新关上。详见用户指南。

Cloudflare Tunnel

和 E 一样是一个普通网址，但不用开放任何端口：服务器上的 cloudflared 主动向外连接 Cloudflare，而 Cloudflare Access 可以要求先用实验室邮箱登录，才能看到 BioManager（最多 50 人 免费）。它需要一个托管在 Cloudflare 上的域名。我们还没有把它做成现成方案；AI 指南里有一些说明， 供 AI 助手设置时参考。

不用 Docker

BioManager 是一个运行在 PostgreSQL 上的 Python 网页应用（gunicorn），前面可以接任何 HTTPS 代理，所以也能在普通服务器上运行。 有了 Docker，备份、更新和恢复都只要一条命令，所以我们推荐用 Docker。

运行起来以后

设置实验室

管理员第一次登录时会打开设置问卷：勾选实验室要管理的内容，BioManager 就只建这些 数据库。详见用户指南。

人员

新注册的账号在管理用户（Manage users）里等待批准。管理员还可以在那里把其他人设为管理员、停用离开的人的账号、重置 密码，以及给动物房工作人员分配动物饲养（Animal care）或动物房主管（Facility manager）角色 （各角色能做什么）。

用 Google、Microsoft 或学校账号登录

可选，每一种只需在 deploy/.env 里加几行再重启（安装包里的 deploy/README.md 有具体步骤）。学校自己的统一登录可以通过 OpenID Connect 接入（Okta、Keycloak、Azure AD、Shibboleth 的 OIDC 插件）：请 IT 部门登记 BioManager，回调地址填 https://DOMAIN/auth/institution/callback， 然后设置 BIOMANAGER_OIDC_ISSUER、_CLIENT_ID、_CLIENT_SECRET 和 BIOMANAGER_OIDC_NAME（登录按钮上显示的文字）。只支持 SAML 的大学（InCommon、eduGAIN） 可以通过 CILogon 接入：设置 BIOMANAGER_CILOGON_CLIENT_ID 和 _SECRET，再用 BIOMANAGER_CILOGON_IDP 直接跳转到你的学校。

带二维码的笼卡

在服务器上，任何能访问服务器的手机扫笼卡上的二维码，就能打开那个笼。实验室网络里的 Zebra 标签打印机 可以直接从服务器接收标签（方法），前提是服务器能连到它： 云上的服务器连不到你实验室里的打印机，除非打印机也接入了 Tailscale。

告警

install.sh 给出的 ntfy 主题会在网站无响应、某个容器停止、硬盘快满 或备份停止时通知你。deploy/RUNBOOK.md 写了每种情况该怎么处理。

更新

操作系统的安全补丁每晚自动安装，容器每周日刷新。升级到新版 BioManager 只要三条命令：

cd /opt/biomanager/Biomanager/deploy
docker compose exec backup backup.sh      # a fresh backup first
curl -fsSL -o /tmp/b.tar.gz https://github.com/gaspolymerase/biomanager/releases/latest/download/biomanager-server.tar.gz \
  && tar -xzf /tmp/b.tar.gz -C /opt/biomanager && host/load-image.sh && docker compose up -d --build

你的 .env 和备份从来不在安装包里，所以直接解压覆盖也会保留它们。新版本启动时会 自动把数据库升级到最新；每个版本发布前都测试过从之前每个版本建立的实验室升级上来。

保护数据安全

鼠群的记录是多年的心血。BioManager 保留多份相互独立的副本，所以任何单一故障， 无论是虚拟机被删、硬盘损坏、笔记本被偷，还是一次有问题的更新，都不会让数据丢失。

恢复也只要一条命令，而且绝不会删掉被替换的数据，见 deploy/RUNBOOK.md。

从桌面版迁到服务器

你在桌面版里录入的所有内容都会一起带过去：记录、历史、编号。用同样的步骤，也能从一台实验室电脑上的副本 重建丢失的服务器：改用它 lab-copies/…/db 文件夹里最新的 .db，以及它的 uploads 文件夹。请在服务器第一次启动之前操作（副本要导入一个空数据库）：

1. 退出桌面版，把它的数据文件夹（见 A）复制到服务器上，例如用 scp 复制到 /tmp/lab。
2. 在服务器上，进入 deploy 文件夹，运行过 host/load-image.sh 并填好 .env 之后：

   docker compose up -d db
   docker compose run --rm --no-deps -v /tmp/lab/biomanager.db:/import/lab.db:ro app \
     sh -c 'python scripts/migrate-to-postgres.py /import/lab.db "$DATABASE_URL"'
   docker compose up -d
   docker compose cp /tmp/lab/uploads/. app:/data/uploads/

3. 用你原来的账号登录。在脚本名后面加 --dry-run 可以先全部检查一遍，不做任何改动。

在已运行的服务器上，主副本也可以不走这些步骤，直接转到桌面版再转回来：管理员在设置 → 设备（Settings → Devices） 里交出主副本，桌面版之后也在那里交还。桌面版持有主副本期间，服务器是只读的，并会显示实验室现在在哪里（设备）。

让 AI 助手来设置

能使用终端的 AI 编程助手（Claude Code、Cursor、Codex 等）可以替你完成 D 或 E 的大部分工作。我们 专门为它写了一份指南，包括相关事实、准确的命令、每一步之后要检查什么，以及安全规则，放在 deploy-with-ai.md。把下面这段话粘贴给你的助手：

只有你能做的部分仍由你掌控：注册云服务和 Tailscale 账号、批准登录，以及 输入密钥和密码。指南会让助手在每一处都停下来问你。

常见问题

免费的云虚拟机真的免费吗？

Oracle 的 Always Free 资源不收费。绑定银行卡是为了验证身份；除非你创建 付费资源，否则不会扣费。免费账号的虚拟机如果闲置一周，可能会被回收；把账号升级为 Pay As You Go（按量付费）就不会被回收，Always Free 资源也仍然不收费。

Tailscale 用来传实验室数据安全吗？

Tailscale 用 WireGuard 加密直接连接各台设备，它自己看不到传输的内容。不在你 tailnet 里的人 根本看不到这台服务器，比一个公开的登录页面难攻击得多。

服务器需要多大？

一个有几万只动物的实验室，数据库也远不到 1 GB。最小的虚拟机就绰绰有余。

能在一台服务器上运行几个实验室吗？

可以每个实验室运行一个 BioManager（各用自己的文件夹和域名），也可以整个动物平台共用一个，每个实验室保留 自己的数据库。

谁能帮忙？

提交一个 issue， 说明你在做什么、卡在了哪一步。