企业官网建设流程全解析

Terminus 是 TRMNL 官方的旗舰级开源项目，一个用于管理 TRMNL 墨水屏设备的自建管理服务器（BYOS，Build Your Own Server）。它基于 Ruby/Hanami 构建，让你在自己的局域网或云端托管环境中拥有完整的设备控制权——你拥有整个技术栈，也拥有自己的数据。🎉

🤔 为什么需要 Terminus？BYOS 与云服务的区别

TRMNL 墨水屏设备原本依赖官方托管服务来刷新画面。但如果你希望：

• 数据完全私有：屏幕内容、设备状态都留在自己的网络内，不经过第三方服务器
• 功能更强：BYOS 版本提供了官方 Core 云端做不到的能力（如账户体系、Docker 部署）
• 成本更低：一次部署长期运行，无需订阅

那么 Terminus 就是为你的墨水屏准备的"自建房"。它在兼容 TRMNL Core 服务器 API 的同时，体验略有差异但功能更全面。

Terminus（BYOS）vs 官方托管功能对比：

📋 核心功能一览：Terminus 能帮你管理什么

安装完成后，你可以在浏览器中管理所有 TRMNL 设备：

• Devices（设备）：自动注册、查看电量/WiFi 信号、配置刷新频率
• Screens（屏幕）：设备实际显示的画面，可批量导入图片、调整渲染模式
• Playlists（播放列表）：把多个屏幕排成轮播，按时序循环展示
• Extensions（扩展）：类似插件，通过 Liquid 模板 + API 数据源生成动态屏幕
• Models / Palettes（型号与调色板）：不同墨水屏型号与色彩方案的管理
• Firmware（固件）：跟随官方"不可变砖承诺"自动同步最新固件
• Dashboard（仪表盘）：一屏纵览所有设备状态

🛠️ 部署前准备：环境要求清单

Terminus 的技术栈以 Ruby 为核心，依赖如下组件（详见 README.adoc 的 Requirements 章节）：

• 必需：Git、Ruby、Hanami、Node、PostgreSQL、Valkey（可用 Redis / Dragonfly 替代）
• 可选：Docker（纯 Ruby 方式部署时可不装）、Google Chrome（屏幕生成用无头浏览器）、Overmind（开发期多进程管理）
• 设备：TRMNL 硬件（也可用虚拟设备先体验）

💡 如果你完全不想碰 Ruby 环境，直接跳过本节，使用下一节的 Docker 一键部署即可。

🚀 最快配置方法：Docker 一键启动 Terminus

这是新手体验 Terminus 的最低成本路径——官方提供了快速启动脚本，位于 scripts/docker/quick.sh，克隆仓库后执行该脚本，即可在本地机器上自动拉起完整的 Docker 栈。

启动成功后，打开浏览器访问：

http://localhost:2300

点击页面上的Register链接完成注册并登录系统，你的 Terminus 管理服务器就上线了。

⚠️注意：快速启动脚本不是幂等的，每次运行都会生成不同的数据库凭据，因此不能重复执行。它只适合快速体验功能，长期生产使用请继续阅读下文的 Docker 部署章节。

📦 标准安装步骤：源码方式部署

想要完全可控的本地环境？按以下步骤操作：

git clone https://gitcode.com/gh_mirrors/terminus13/terminus cd terminus bin/setup

• 安装脚本是幂等的，可放心多次执行
• 若需重建某个由脚本生成的文件，删除该文件后重跑bin/setup即可

启动服务器：

# 开发环境 overmind start --port-step 10 --procfile Procfile.dev --can-die assets,migrate # 生产环境 overmind start --port-step 10 --can-die assets,migrate

进程编排由 Procfile 定义，多进程管理依赖 Overmind（参见 doc/development.adoc）。

访问地址（二选一）：

• 🔒 安全入口：https://localhost:2443
• 普通入口：http://localhost:2300

👤 首个账户规则：谁先注册谁是管理员

Terminus 启动后默认没有任何用户。遵循以下规则：

• 第一个注册的用户自动获得Verified身份，拥有系统全部权限
• 后续注册的用户默认是Unverified，需要管理员在用户管理中手动验证后才能访问
• 登录后可以在/me/login、/me/password、/me/remember更新邮箱、密码和免登录设置

📶 连接第一台 TRMNL 设备

设备接入是 BYOS 的核心价值所在，流程如下：

1. 用手机连接设备发出的WiFi 捕获门户（captive portal），将设备接入运行 Terminus 的同一局域网
2. 设备首次向服务器发起 Display API 请求时，会自动完成注册（auto-provisioning），并根据 Models 页面识别对应型号
3. 之后设备按刷新频率定时拉取屏幕画面，服务器同时回收电量、WiFi 信号等上报数据

常见型号兼容提示：

更多型号细节见 doc/devices.adoc。

🐳 生产环境部署：Docker Compose 与关键配置

长期运行的推荐方式是 Docker Compose，项目根目录已提供 compose.yml（生产）与compose.dev.yml（开发），官方还提供预编译镜像（支持 AMD64 / ARM64）：

# 拉取官方预编译镜像 docker pull ghcr.io/usetrmnl/terminus:latest # 启动完整生产栈 docker-compose up

两个必须关注的环境变量（配置在.env文件中，详情见 doc/configuration.adoc）：

• API_URI：设备连接服务器的地址。服务器 IP 变化或设置脚本未能自动检测时，必须手动更新——服务器与设备两端必须指向同一个 URI
• HANAMI_PORT：应用端口（默认 2300）

修改环境变量后需重启 Docker 才能生效。完整变量清单（会话时长、超时时间、Rack Attack 子网白名单等）都在 Configuration 文档中逐一说明。

其他部署场景：

• 🍓树莓派：官方已测试 Raspberry Pi 5 与 Pi Zero 2 W，可参考 doc/raspberry_pi.adoc
• ☁️Render 云部署：参见 doc/render.adoc
• 🌐Kubernetes：社区项目 Terminus Kubernetes 提供完整自动化方案

🧩 进阶玩法：Extensions 扩展系统

Terminus 的扩展（Extensions）相当于插件：你可以通过界面创建扩展，绑定 API 数据源（exchange）+ Liquid 模板，让墨水屏实时展示天气、日程、行情等动态内容。

官方文档用一个"动漫电影 API"的完整示例手把手演示了创建、配置数据源、预览渲染的全过程，推荐按 doc/extensions.adoc 的 Walkthrough 章节动手试一次。

相关源码入口：app/actions/extensions/、app/aspects/extensions/。

📖 官方文档导航：遇到问题先查这里

✅ 总结

Terminus 是 TRMNL 墨水屏玩家实现数据自主、功能全开的自建管理服务器。三步即可完成入门：克隆仓库 → 执行 setup → 浏览器注册登录，随后接入设备、配置播放列表，就能享受完全属于自己的墨水屏内容中心。项目目前仍处于 Beta 阶段（未到 1.0.0），升级时留意bin/upgrade的输出提示即可。