feat: add trailbase

2025-12-29 11:33:23 +08:00
parent 74cc6b49a7
commit 4c7b3afc10
6 changed files with 695 additions and 406 deletions
--- a/src/trailbase/README.zh.md
+++ b/src/trailbase/README.zh.md
@@ -0,0 +1,110 @@
+# TrailBase
+
+[English](./README.md) | [中文](./README.zh.md)
+
+TrailBase 是一个开源的单可执行后端，提供 type-safe REST 与实时 API、内置管理界面、WebAssembly 运行时以及身份认证功能，底层由 Rust、SQLite 与 Wasmtime 驱动。
+本配置使用官方 Docker 镜像并提供合理的默认值，方便你立即访问管理后台、定义数据模型并在本地体验 TrailBase。
+
+## 服务
+
+- `trailbase`：包含管理后台、REST API 以及实时通道的核心服务。
+
+## 快速开始
+
+1. 复制示例环境文件并按需修改：
+
+   ```bash
+   cp .env.example .env
+   ```
+
+2. 启动服务：
+
+   ```bash
+   docker compose up -d
+   ```
+
+3. 首次启动会在日志中输出自动生成的管理员账号，使用以下命令查看：
+
+   ```bash
+   docker compose logs -f trailbase
+   ```
+
+4. 打开 `http://localhost:4000/_/admin`，使用日志中的凭据登录（或按照下文创建新的管理员）。
+
+## 默认访问入口
+
+| 入口                                    | 说明                |
+| --------------------------------------- | ------------------- |
+| `http://localhost:4000/_/admin`         | 管理界面            |
+| `http://localhost:4000/api/healthcheck` | 健康检查端点        |
+| `http://localhost:4000/_/auth/login`    | 可选的 Auth UI 入口 |
+
+## 环境变量
+
+| 变量名                         | 描述                                | 默认值   |
+| ------------------------------ | ----------------------------------- | -------- |
+| `TRAILBASE_VERSION`            | Docker 镜像标签                     | `0.22.4` |
+| `TRAILBASE_PORT_OVERRIDE`      | 暴露到宿主机的端口（容器端口 4000） | `4000`   |
+| `TRAILBASE_RUST_BACKTRACE`     | 是否输出 Rust 堆栈，便于排障        | `1`      |
+| `TRAILBASE_LOG_MAX_SIZE`       | `json-file` 日志的最大文件大小      | `100m`   |
+| `TRAILBASE_LOG_MAX_FILE`       | 日志轮转时保留的文件数量            | `3`      |
+| `TRAILBASE_CPU_LIMIT`          | CPU 限制（`deploy.resources`）      | `1.0`    |
+| `TRAILBASE_MEMORY_LIMIT`       | 内存限制                            | `1G`     |
+| `TRAILBASE_CPU_RESERVATION`    | CPU 预留                            | `0.25`   |
+| `TRAILBASE_MEMORY_RESERVATION` | 内存预留                            | `256M`   |
+| `TZ`                           | 容器时区                            | `UTC`    |
+
+完整说明请参考 `.env.example`。
+
+## 数据卷
+
+- `trailbase_data`：对应容器内的 `traildepot`，保存 SQLite 数据库、WASM 组件、认证密钥及上传的静态资源。升级或迁移前务必备份该卷。
+
+## 初始化与管理员账号
+
+- 首次启动后，TrailBase 会在日志中打印一次性管理员账号与密码。请立即登录并修改。
+- 也可以直接在容器内创建新的已验证用户：
+
+  ```bash
+  docker compose exec trailbase /app/trail user add admin@example.com "StrongPassw0rd!"
+  ```
+
+- 使用同一个 `trail` CLI 可以重置密码、导入导出数据等，不需要重启服务。
+
+## 可选组件
+
+- 镜像已经预置官方 Auth UI WASM 组件，若需要其他组件，可在运行中安装：
+
+  ```bash
+  docker compose exec trailbase /app/trail components add trailbase/auth_ui
+  docker compose exec trailbase /app/trail components add your-org/your-component
+  ```
+
+- 如果希望通过 Git 管理组件或静态资源，可以将本地目录挂载到 `trailbase_data`。
+
+## 健康检查与维护
+
+- 默认健康检查请求 `http://localhost:4000/api/healthcheck`，也可以手动使用 `curl` 进行验证。
+- 备份流程示例：
+
+  ```bash
+  docker compose stop trailbase
+  docker run --rm -v compose-anything_trailbase_data:/data -v $(pwd):/backup alpine tar czf /backup/trailbase-backup.tar.gz -C /data .
+  docker compose start trailbase
+  ```
+
+- 恢复时将备份解压回同名数据卷即可。
+
+## 安全提示
+
+- 启动后立即更换默认管理员凭据，并在防火墙或反向代理层限制 4000 端口的访问。
+- 生产环境建议将 `TRAILBASE_RUST_BACKTRACE` 设置为 `0`，避免日志泄露系统细节。
+- 配合 Caddy、nginx 或 Traefik 等反向代理启用 TLS，必要时再开启 WAF、IP 白名单等防护。
+- 升级新版本前务必备份 `trailbase_data` 数据卷。
+
+## 参考资料
+
+- 官网：<https://trailbase.io>
+- 仓库：<https://github.com/trailbaseio/trailbase>
+- 文档：<https://trailbase.io/reference>
+- 许可证：Open Software License 3.0（OSL-3.0）