subspace-api

subspace-trmnl

subspace-trmnl 是运行 subtype 创建的 TRMNL 插件的服务。

所有 TRMNL 设备所有者均可免费使用此服务。

开始使用

使用 Docker（推荐使用 compose）

构建自己的镜像

docker compose build && docker compose up -d

从稳定版本拉取

docker compose pull && docker compose up -d

手动构建

npm run build && npm run start

环境变量

核心（可选）

环境变量	默认值	用途
PORT	9595	服务监听的端口
LOG_LEVEL	info	日志详细程度（debug、info、warn、error）
ACTIVE_VERSION	v1	API 版本前缀（尚未完全实现）
TZ	-	容器的时区，用于日志时间戳（例如 America/New_York）
PUBLIC_BASE_URL	-	用于构建提供静态资源的绝对 URL

TRMNL 插件设置

如果运行 TRMNL 插件（地铁或航班追踪器），则必须设置以下变量。

环境变量	必填	用途
TRMNL_CLIENT_ID	是	TRMNL 为你的插件提供的 OAuth 2.0 客户端 ID
TRMNL_CLIENT_SECRET	是	与 TRMNL_CLIENT_ID 配套的 OAuth 2.0 客户端密钥
WMATA_PRIMARY_KEY	地铁插件必填	用于华盛顿特区地铁到站预测和突发事件的 WMATA API 密钥
TRMNL_FLIGHTS_CLIENT_ID	航班插件必填	TRMNL 航班追踪器插件的 OAuth 2.0 客户端 ID
TRMNL_FLIGHTS_CLIENT_SECRET	航班插件必填	与 TRMNL_FLIGHTS_CLIENT_ID 配套的 OAuth 2.0 客户端密钥
AERODATABOX_API_KEY	航班插件必填	用于 AeroDataBox（实时航班状态数据）的 RapidAPI 密钥
TRMNL_DB_PATH	否	SQLite 数据库文件的路径（默认值：./trmnl.sqlite）
TRMNL_IP_ALLOW_PRIVATE	否	设为 true 可绕过 TRMNL worker IP 允许列表检查（适用于本地开发）

发布版本

注意：发布由 Agent 按照 CLAUDE.md 中的说明执行。把这项工作交给它处理，并由它维护标签和进行清理，会更轻松。 所有开发更新都应在 dev 分支中进行。拉取请求应针对当前活跃版本（例如 v1）提交。合并到活跃版本分支后，必须向该分支推送一个标签以“切出”发布版本。

AI 使用说明

本项目的部分内容借助 Claude Code 完成，Claude Code 为实现提供了示例。 Claude Code 还提出建议，对代码库的部分内容进行了重构，以提高效率。 除非另有说明，代码库大部分由手工编写。OAuth 2.0 规范的部分实现得到了大模型的协助。 TRMNL Flight Tracker 逻辑中有关计算的部分得到了大模型的协助，信息展示也是如此，但并非凭空生成。

subspace 有责任检查这些大模型的输出，确保其准确性、实现细节和方向正确。

附录

代码风格（尤其是注释风格）非常不统一。这不是 AI 造成的，只是因为使用 Intellisense 时比较懒，也太喜欢用 /** 编写文档。

免责声明与合理使用

此航班追踪器包含多家航空公司和航空运营商的徽标与横幅。

合理使用声明： 这些图片归各自所有者（航空公司和运营商）所有。此处提供这些图片仅用于教育和识别目的（例如，在航班追踪应用中识别航空公司）。

• 根据版权法，这种用法属于合理使用，因为它是非商业性的、具有转换性（汇总信息以便识别），并且不会妨碍所有者通过其品牌获利。
• 本仓库不主张拥有任何商标或受版权保护的材料。