tianma-if
be7bbe25e6
Official entries stay on the bundled registry. The instance returns a community file only when EDGE_EVER_COMMUNITY_REGISTRY_URL is set, and submission opens from its own marketplace entry.
181 lines
8.2 KiB
Markdown
181 lines
8.2 KiB
Markdown
# 使用 Docker 部署 EdgeEver
|
||
|
||
EdgeEver 在 Cloudflare 与 Docker 中共用同一套 Web 应用、Hono 路由、业务服务、
|
||
鉴权、MCP 实现和只增不改的 migration。两种部署仅有薄运行入口和基础
|
||
设施适配器不同：Docker 使用 Bun + SQLite + 本地文件（或 S3 兼容对象存储），
|
||
Cloudflare 使用 Workers + D1 + R2。
|
||
|
||
## 环境要求
|
||
|
||
- Docker Engine 24 或更高版本，包含 Docker Compose v2。
|
||
- `amd64` 或 `arm64` Linux 主机。
|
||
- Linux 5.6 或更高版本内核。更旧的内核不属于正式支持的 Docker 环境，因为 Bun
|
||
在这些环境中可能无法解析容器依赖。安装器会发出警告但不会阻止安装；如果启动
|
||
日志出现 `EISDIR reading .../node_modules/...`，应先升级宿主机系统或内核，
|
||
不要先修改 `/data` 权限或替换应用数据。
|
||
- 实例离开可信局域网时，必须使用带 HTTPS 的反向代理。
|
||
|
||
## 一键安装
|
||
|
||
已安装 Docker Compose v2 的主机可直接执行：
|
||
|
||
```sh
|
||
curl -fsSL https://edgeever.org/install.sh | bash
|
||
```
|
||
|
||
脚本会创建 `~/edgeever`、生成管理员密码、拉取 `latest`、启动容器并等待健康
|
||
检查通过。安装脚本和 Compose 配置使用官方 GHCR 镜像。再次执行同一命令即可
|
||
升级，已有密码和 `/data` 卷保持不变。
|
||
|
||
> 💡 **网络提示**：官方镜像托管于 GitHub（GHCR）。若在部分网络环境下遇到拉取缓慢或超时，请在部署前自行配置可用的网络代理或可信的镜像加速服务。
|
||
|
||
默认情况下，脚本会通过当前用户的 crontab 设置每日自动更新，于服务器本地时间
|
||
04:17 执行 `~/edgeever/update.sh`。更新程序会刷新 Compose 配置、拉取已配置的
|
||
镜像标签、按需重建服务并验证容器健康状态，运行记录追加到
|
||
`~/edgeever/update.log`。默认的 `latest` 标签会自动获得新版本；通过 `--version`
|
||
指定的版本保持固定。使用 `--no-auto-update` 或
|
||
`EDGE_EVER_AUTO_UPDATE=false` 可关闭自动更新。如果系统没有 `crontab`，安装脚本
|
||
会保留 `update.sh`，并提示通过 NAS 的任务计划程序执行。
|
||
|
||
按需使用 `--version vX.Y.Z`、`--port PORT` 或 `--install-dir DIR`；执行以下命令
|
||
可查看全部参数：
|
||
|
||
```sh
|
||
curl -fsSL https://edgeever.org/install.sh | bash -s -- --help
|
||
```
|
||
|
||
## 手动使用 Compose
|
||
|
||
下载 `compose.yaml`，选择要运行的正式版本，并设置高强度实例密码：
|
||
|
||
```sh
|
||
export EDGE_EVER_VERSION=vX.Y.Z
|
||
export EDGE_EVER_AUTH_PASSWORD='请替换为足够长的随机密码'
|
||
docker compose up -d
|
||
docker compose ps
|
||
```
|
||
|
||
打开 `http://localhost:8787`。只有共享的 `/api/health` 确认鉴权、SQLite 和对象
|
||
存储均已就绪后，容器才会进入 healthy 状态。
|
||
|
||
### 镜像地址
|
||
|
||
官方镜像为 `ghcr.io/tianma-if/edgeever`，支持 `linux/amd64` 与 `linux/arm64`。
|
||
生产环境应通过 `EDGE_EVER_VERSION` 固定正式版本标签。
|
||
|
||
Compose 会创建一个命名卷。所有需要在容器替换后保留的数据都位于 `/data`：
|
||
|
||
```text
|
||
/data/edgeever.sqlite SQLite 数据库
|
||
/data/edgeever-secrets.json 凭据加密根密钥
|
||
/data/resources/ 本地图片与附件
|
||
```
|
||
|
||
镜像以非 root 的 `bun` 用户运行（UID/GID 均为 `1000`）。如果 NAS 必须使用主机
|
||
目录绑定而不是命名卷，请先创建目录，并为 UID/GID `1000` 授予读写权限。
|
||
安装或自动更新失败时，脚本会对 `/data` 执行实际写入测试，输出挂载类型、来源、
|
||
容器用户和目录状态。确认是权限问题后，还会根据 Docker 命名卷或 NAS 目录绑定
|
||
给出对应的修复命令；脚本不会擅自修改现有数据的权限。
|
||
|
||
## 配置
|
||
|
||
常用环境变量：
|
||
|
||
| 变量 | 默认值 | 用途 |
|
||
| -------------------------------------- | -------- | ----------------------------------------- |
|
||
| `EDGE_EVER_AUTH_USERNAME` | `admin` | 初始管理员用户名 |
|
||
| `EDGE_EVER_AUTH_PASSWORD` | 无 | 初始密码；新数据库必须提供 |
|
||
| `EDGE_EVER_AUTH_PASSWORD_HASH` | 无 | 可替代明文引导密码的 PBKDF2 hash |
|
||
| `EDGE_EVER_SESSION_TTL_DAYS` | `400` | 登录会话有效期 |
|
||
| `EDGE_EVER_IDLE_TIMEOUT_SECONDS` | `120` | Bun 流式响应空闲超时，可设为 10 到 255 秒 |
|
||
| `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` | 写入 `/data` | 可选的独立 AI 凭据加密密钥。未设置时，Docker 会把认证 Secret 或自动生成的密钥写入 `/data/edgeever-secrets.json`。 |
|
||
| `EDGE_EVER_COMMUNITY_REGISTRY_URL` | 不设置 | 可选。签名社区插件目录的 HTTPS 地址。不设置时，市场只显示内置官方插件。 |
|
||
|
||
Secret 可在受支持的变量名后追加 `_FILE`，并指向 Docker secret，例如
|
||
`EDGE_EVER_AUTH_PASSWORD_FILE=/run/secrets/auth_password`。密码/hash 和 S3
|
||
访问凭据均支持这种形式。同一个 Secret 不得同时设置直接变量与
|
||
对应的 `_FILE` 变量。
|
||
|
||
`EDGE_EVER_ALLOW_UNAUTHENTICATED=true` 仅用于隔离的开发环境，严禁将未鉴权
|
||
实例暴露到网络。
|
||
|
||
## 使用 S3 兼容附件存储
|
||
|
||
SQLite 仍保存在 `/data`，新附件可以写入 MinIO、AWS S3、阿里云 OSS、腾讯云
|
||
COS、R2 或其他兼容服务：
|
||
|
||
```yaml
|
||
environment:
|
||
EDGE_EVER_STORAGE_BACKEND: s3
|
||
EDGE_EVER_S3_ENDPOINT: https://s3.example.com
|
||
EDGE_EVER_S3_REGION: us-east-1
|
||
EDGE_EVER_S3_BUCKET: edgeever
|
||
EDGE_EVER_S3_ACCESS_KEY_ID_FILE: /run/secrets/s3_access_key
|
||
EDGE_EVER_S3_SECRET_ACCESS_KEY_FILE: /run/secrets/s3_secret_key
|
||
EDGE_EVER_S3_FORCE_PATH_STYLE: "true"
|
||
```
|
||
|
||
切换默认后端不会迁移历史附件。在完成导出或迁移前，必须保持旧后端可用。
|
||
|
||
## HTTPS 与网络暴露
|
||
|
||
容器在 `8787` 端口提供 HTTP。请使用维护活跃的 Caddy、Traefik 或 Nginx 终止
|
||
HTTPS，并转发原始 Host 和客户端地址。严禁公开 SQLite、`/data` 或对象存储的
|
||
管理端口。
|
||
|
||
## 备份与恢复
|
||
|
||
可使用 EdgeEver ZIP 导出制作跨环境内容备份，同时应冷备份 `/data` 卷以支持
|
||
完整实例恢复：
|
||
|
||
1. 执行 `docker compose stop edgeever`，等待日志出现 shutdown complete。
|
||
EdgeEver 会在优雅停机时 checkpoint SQLite WAL。
|
||
2. 完整复制或快照命名卷，包括 SQLite 文件、`edgeever-secrets.json` 与
|
||
`resources` 目录。
|
||
3. 执行 `docker compose start edgeever` 恢复服务。
|
||
|
||
Docker 会把凭据加密根密钥保存在 `/data/edgeever-secrets.json`，因此完整的
|
||
`/data` 卷备份在容器重建后仍可解密已保存的 AI 与对象存储凭据。如果你在数据卷
|
||
之外单独管理密钥，请继续备份显式配置的
|
||
`EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY`。Cloudflare 部署仍使用 Worker Secret，
|
||
不会读写该文件。使用 S3 时还需独立备份存储桶。
|
||
|
||
只能在 EdgeEver 停止时恢复到空卷。应定期在独立实例中验证备份。
|
||
|
||
## 升级与回滚
|
||
|
||
生产环境应使用不可变的正式版本标签，不要依赖 `latest`：
|
||
|
||
```sh
|
||
export EDGE_EVER_VERSION=vX.Y.Z
|
||
docker compose pull
|
||
docker compose up -d
|
||
docker compose ps
|
||
```
|
||
|
||
容器会在接收流量前应用与 D1 共用的 `migrations/*.sql`。升级前必须先备份。
|
||
回退应用镜像不会逆向撤销数据库 migration；需要回退数据时，应恢复升级前的
|
||
卷备份。
|
||
|
||
镜像默认命令是 `bun scripts/self-hosted-server.js`，同时保留
|
||
`scripts/self-hosted-server.mjs` 作为别名，因为 NAS/GUI 面板常会沿用 v1.62
|
||
及更早版本保存的启动命令。如果日志出现
|
||
`Module not found "scripts/self-hosted-server.mjs"`，请拉取包含该别名的版本，
|
||
或清空自定义命令以使用镜像默认入口。
|
||
|
||
在 Cloudflare 与 Docker 之间迁移时，请使用 EdgeEver 的完整备份/导出与恢复
|
||
流程。不要复制在线 D1 数据库文件，也不要改写 migration 历史。
|
||
|
||
## 从源码构建
|
||
|
||
```sh
|
||
docker build --tag edgeever:local .
|
||
docker run --rm -p 8787:8787 \
|
||
-e EDGE_EVER_AUTH_PASSWORD='请替换为足够长的随机密码' \
|
||
-v edgeever-data:/data \
|
||
edgeever:local
|
||
```
|
||
|
||
Docker 首发版本不支持 PostgreSQL。它仍是未来的存储适配器，不会形成另一套
|
||
业务代码分支。
|