Ente 自托管服务器升级指南：Quickstart / Docker Compose / 手动部署三种方式详解-平芜编程栈

Ente 自托管服务器升级指南：Quickstart / Docker Compose / 手动部署三种方式详解

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente

导读

本指南聚焦于 Ente 自托管（Self-hosting）场景下的服务器升级流程。Ente 是一个端到端加密的云服务（照片、认证器、Cast 等），其自托管部署有多种方式——Quickstart 脚本、基于源码的 Docker Compose、以及脱离 Docker 的手动部署——而升级方式完全取决于你当初选择的安装方式。读完本文，你将掌握三种方式各自的镜像拉取、源码更新、容器重建与数据保留策略，并了解升级前后必须注意的镜像路径迁移（ghcr.io/ente-io/→ghcr.io/ente/）、磁盘清理、健康检查等关键细节。

[!IMPORTANT] 如果你的 Compose 文件中引用了ghcr.io/ente-io/，请将其替换为ghcr.io/ente/，然后执行docker compose pull && docker compose up -d。

升级前必读：镜像路径迁移（ghcr.io/ente-io → ghcr.io/ente）

Ente 已将 GitHub 组织从ente-io更名为ente。虽然大部分 Web 链接仍然会重定向到新地址，但GitHub Container Registry（GHCR）不会为重命名后的路径做重定向，因此预构建镜像的位置已经发生了迁移。

旧路径（已失效）	新路径
`ghcr.io/ente-io/server`	`ghcr.io/ente/server`
`ghcr.io/ente-io/web`	`ghcr.io/ente/web`

故障现象：如果 Compose 文件仍引用旧路径，docker compose pull会以denied错误失败，因为ghcr.io/ente-io/server与ghcr.io/ente-io/web已不存在（详见 troubleshooting/ghcr.md）。

修复方式：更新 Compose 文件中的image引用（Quickstart 场景下即my-ente目录中的compose.yaml），从ghcr.io/ente-io/改为ghcr.io/ente/，然后拉取新镜像并重建集群：

docker compose pull && docker compose up -d

如果你是从源码构建而非使用预构建镜像，则无需修改此处——只需拉取最新的main分支并按常规流程重新构建即可。

升级方式的总体原则

升级 Ente 服务器取决于你选择的安装方法，共有三种对应路径：

Quickstart 脚本安装（推荐，使用预构建镜像）——通过docker compose pull拉取新镜像并重建容器。
Docker Compose 源码构建——git pull获取最新源码，然后docker compose down && docker compose up --build重新构建并重建集群。
手动部署（无 Docker）——git fetch origin && git reset --hard main更新源码，随后重新构建 Museum 服务端与 Web 应用。

无论哪种方式，数据卷（volume）与配置文件（如museum.yaml、data目录）都不会被破坏，升级的本质是替换可执行程序或容器镜像，而不是重新初始化数据。

方式一：Quickstart 脚本安装的升级

Quickstart 是官方推荐的快速部署方式，通过一行命令在不到一分钟内完成 Ente 的自托管初始化（见 quickstart.md）。该脚本会在当前工作目录创建my-ente目录，并在其中生成compose.yaml与museum.yaml，同时自动生成数据库密码、MinIO 凭证、Museum 加密密钥（key.encryption）、哈希密钥（key.hash）与 JWT 密钥等敏感信息（见 server/quickstart.sh）。

升级步骤非常简单：在存放 Compose 文件的目录中拉取最新镜像，然后重启集群以用新镜像重建容器。

在my-ente目录（Quickstart 的默认目录名）中执行：

docker compose pull && docker compose up -d

docker compose pull：从 GHCR 拉取ghcr.io/ente/server与ghcr.io/ente/web的最新镜像；
docker compose up -d：以新镜像重建并后台启动全部服务（museum、socat、postgres、minio、web）。

升级后释放磁盘空间

[!TIP] 可以通过删除旧容器曾经使用的旧版镜像来释放一些磁盘空间：

docker image prune

docker image prune会删除所有不再被任何容器引用的悬空镜像（dangling images）。如果希望更彻底地清理（例如删除旧版本的标签镜像），可以配合docker image prune -a，但请确认没有正在运行的容器依赖这些镜像。

Quickstart 集群的组成（升级前需了解）

通过server/quickstart.sh生成的compose.yaml包含以下服务（见 server/quickstart.sh）：

服务	镜像	宿主端口	用途
`museum`	`ghcr.io/ente/server`	8080	Ente 的 Go 服务端（Museum/API）
`socat`	`alpine/socat`	—	将容器内`localhost:3200`转发到 minio 容器
`web`	`ghcr.io/ente/web`	3000、3002（其余默认注释）	Photos 与 Albums Web 应用
`postgres`	`postgres:15`	—	数据库（不对外暴露端口）
`minio`	`minio/minio`	3200	本地对象存储（S3 兼容）

其中museum与web两个服务在升级时会随镜像更新而被替换，而postgres-data、minio-data两个命名卷中的数据会完整保留，因此升级不会丢失照片、账号等业务数据。

升级后，Photos 应用仍可从http://localhost:3000（或http://<machine-ip>:3000）访问，公共相册链接由 Albums 应用在http://localhost:3002（或http://<machine-ip>:3002）提供。Museum 访问的数据存放在my-ente目录下的./data文件夹中，其中包含后续可用的附加配置文件（如推送通知凭证等）。若需要进一步配置（域名、自定义端点、推送通知等），可参考 post-install/index.md。

方式二：Docker Compose 源码构建的升级

如果当初是克隆仓库后基于源码构建集群（即 compose.md 描述的方式，在server/config目录下执行docker compose up --build），那么升级就是从 Git 拉取最新源码，并基于更新后的源码重建整个集群。

步骤 1：拉取`main`分支的最新变更

# 假设已将仓库克隆到 ente cd ente # 拉取变更 git pull

步骤 2：重建集群

cd server/config # 停止并移除正在运行的容器（如果它们正在运行） docker compose down # 用最新代码重新构建 docker compose up --build

这里的关键点：

docker compose down会停止并移除容器，但不会删除命名卷（postgres-data、minio-data），因此数据库与对象存储数据得以保留；
docker compose up --build会根据server/config/compose.yaml（见 compose.yaml）中的build指令重新构建museum（构建上下文为..，即server目录）与ente-web（构建上下文为../..，Dockerfile 为web/Dockerfile），然后启动包含 postgres、minio、socat 在内的完整集群。

源码构建的配置注意点

从源码构建时，配置是从server/config下的example.env与example.yaml拷贝而来（见 compose.md）：

# 在克隆仓库的目录（通常是 ente）内 cd server/config cp example.env .env cp example.yaml museum.yaml

[!TIP] 请确保数据库与对象存储的值正确。如果打算长期使用，建议为 JWT 与邮件加密密钥生成新值。在ente/server目录下执行以下命令即可生成：

cd ente/server go run tools/gen-random-keys/main.go

相关工具源码位于 server/tools/gen-random-keys，它会基于crypto_secretbox_KEYBYTES = 32（加密密钥）、crypto_generichash_BYTES_MAX = 64（哈希密钥）等长度生成随机密钥，Quickstart 脚本内部也使用了相同长度的生成逻辑（见 server/quickstart.sh）。

方式三：手动部署（无 Docker）的升级

对于完全脱离 Docker、从源码运行 Museum 与 Web 应用的手动部署（见 manual.md），升级流程分为两步：先同步源码，再按手动安装的第 3 步（配置 Web 应用）重新构建 Museum 与各 Web 应用。

步骤 1：拉取`main`分支的最新变更

# 假设已将仓库克隆到 ente cd ente # 拉取变更，且只保留来自远程的变更。 # 这是为了保持 package-lock.json 始终最新。 # 这会重置本地仓库中的所有变更。 # 如果做了任何修改，请务必先 stash 保存。 git fetch origin git reset --hard main

[!CAUTION]git reset --hard main会丢弃本地所有未提交的修改。如果你对源码或配置文件做过本地改动，请务必先用git stash（或提交）保存，否则这些改动会丢失。文档特别指出这一步是必要的，因为它可以保持package-lock.json与远程一致。

步骤 2：按照手动安装的步骤 3 重新构建 Museum 与 Web 应用

手动安装的完整流程（详见 manual.md）包括：

重建 Museum（Ente 的服务端）：

# 进入 server 目录，Museum 源码位于其中 cd ente/server # 安装依赖 go mod tidy # 构建服务端，二进制文件将出现在 server 目录下，名为 ./main go build cmd/museum/main.go

重建 Web 应用：

# 进入 web 目录 cd ../web # 安装依赖 npm ci # 构建所需应用（Photos、Albums、Accounts、Auth、Cast、Public Locker、Embed、Memories） npm run build npm run build:albums npm run build:accounts npm run build:auth npm run build:cast npm run build:share npm run build:embed npm run build:memories

构建产物分别位于web/apps/<app>/out，需要按手动安装的步骤 4 拷贝到/var/www/ente/apps下由 Caddy 托管。

[!TIP] 升级时请确认 Web 应用的环境变量仍然指向 Museum 端点。手动部署时需要在 shell 配置文件（.bashrc、.zshrc）中设置NEXT_PUBLIC_ENTE_ENDPOINT（即ENTE_API_ORIGIN的别名），例如export NEXT_PUBLIC_ENTE_ENDPOINT=http://localhost:8080。如果 Museum 端点在升级前后发生了变化，这里必须同步更新并重新构建 Web 应用。

升级前后必须核对的环境与配置要点

无论采用哪种升级方式，以下要点都值得在升级前核对（详见 env-var.md 与 config.md）：

环境变量

服务	环境变量	描述	默认值
`web`	`ENTE_API_ORIGIN`	`NEXT_PUBLIC_ENTE_ENDPOINT`的别名，即 Museum API 端点	`http://localhost:8080`
`postgres`	`POSTGRES_USER`	PostgreSQL 用户名	`pguser`
`postgres`	`POSTGRES_DB`	数据库名	`ente_db`
`postgres`	`POSTGRES_PASSWORD`	数据库密码	Quickstart 随机生成
`minio`	`MINIO_ROOT_USER`	MinIO 用户名	Quickstart 随机生成
`minio`	`MINIO_ROOT_PASSWORD`	MinIO 密码	Quickstart 随机生成

在 Quickstart 生成的compose.yaml中，Web 容器通过ENTE_API_ORIGIN: http://localhost:8080指向 Museum；如果你的 Museum 地址是自定义的（如配置了域名），升级后需确保该值仍然正确。

端口一览

服务	类型	宿主端口
Museum	服务端	8080
Ente Photos	Web	3000
Ente Accounts	Web	3001
Ente Albums	Web	3002
Ente Auth	Web	3003
Ente Cast	Web	3004
Ente Public Locker	Web	3005
Ente Embed	Web	3006
Ente Paste（独立部署时）	Web	3008
Ente Locker	Web	3009
Ente Memories	Web	3010
MinIO	S3	3200

注意：Quickstart 生成的compose.yaml默认只暴露3000（Photos）与3002（Albums），其余端口以注释形式存在，需要时取消注释即可（见 server/quickstart.sh）。

museum.yaml 的配置覆盖机制

升级过程中如果修改了museum.yaml，需了解 Museum 的配置加载规则（详见 config.md）：

默认运行在本地环境，加载configurations/local.yaml；设置ENVIRONMENT环境变量（如production）后，Museum 会尝试加载configurations/production.yaml；
所有配置值都可以通过环境变量覆盖：使用ENTE_前缀，并将点（.）或连字符（-）替换为下划线（_）。例如museum.yaml中的s3.b2-eu-cen.endpoint等价于环境变量ENTE_S3_B2_EU_CEN_ENDPOINT，且环境变量优先级更高；
credentials-file若被定义且存在，则覆盖默认值。

在 Quickstart 生成的museum.yaml中，对象存储默认使用本地 MinIO（are_local_buckets: true、use_path_style_urls: true），并配置了b2-eu-cen、wasabi-eu-central-2-v3、scw-eu-fr-v3三个桶（见 server/quickstart.sh）。如果你升级后切换到外部 S3 提供商（带 SSL），需要将对应配置改为外部凭证，并将are_local_buckets设为false。

版本前提：Docker Compose 2.30+

Ente 要求Docker Compose 版本 2.30 或更高，并且只支持docker compose子命令形式，docker-compose（连字符版本）已不再受支持（见 requirements.md）。Quickstart 脚本在运行时会显式检查 Compose 版本，低于 2.30 会直接报错退出（见 server/quickstart.sh）：

ERROR: Docker Compose version (x.y.z) should be at least 2.30+ for running this script.

硬件方面，运行整个集群（Quickstart 方式）至少需要 1 GB RAM 与 1 个 CPU 核心；Museum 作为轻量级 Go 二进制，大多数计算密集型任务在客户端完成，因此对小云主机、老旧笔记本甚至低端嵌入式设备都能良好运行。

升级后的验证与常见问题

验证升级是否成功

检查容器状态：在 Compose 目录执行docker compose ps，确认所有服务均为Up（healthy）状态。
访问 Web 应用：打开http://localhost:3000，确认 Photos 应用正常加载；公共相册链接确认http://localhost:3002可用。
API 健康检查：Quickstart 的museum容器内置了健康检查，通过wget --spider http://localhost:8080/ping探测/ping端点（见 server/quickstart.sh）。升级后也可手动访问http://localhost:8080/ping验证 Museum 是否就绪。
观察日志：Quickstart 模式下，新用户注册的账户验证码会打印在docker compose logs中，可用于确认服务正常处理请求。

常见问题

问题	原因与处理
`docker compose pull`报`denied`	Compose 文件仍引用`ghcr.io/ente-io/`旧路径，替换为`ghcr.io/ente/`后重新`pull`（详见 troubleshooting/ghcr.md）
升级后数据“丢失”	大概率是容器卷未挂载正确。Quickstart 与 Compose 方式均使用命名卷（`postgres-data`、`minio-data`），切勿删除卷；`museum.yaml`与`data`目录通过只读挂载（`:ro`）提供给 Museum 容器
上传/下载异常	检查对象存储配置与 CORS 设置，参见 troubleshooting/uploads.md 与 administration/object-storage.md
`git reset --hard main`后本地改动丢失	升级前未 stash。手动部署升级前务必`git stash`或提交本地修改

总结

Ente 自托管的升级策略可以一句话概括：按安装方式选择对应的升级路径。

Quickstart（预构建镜像）：cd my-ente && docker compose pull && docker compose up -d，必要时docker image prune清理旧镜像；
Docker Compose（源码构建）：git pull后cd server/config && docker compose down && docker compose up --build；
手动部署（无 Docker）：git fetch origin && git reset --hard main同步源码，然后重新go build cmd/museum/main.go与各 Web 应用构建命令。

无论哪种方式，升级都不会触碰命名卷与配置文件中的数据，业务数据天然安全；需要特别注意的是ghcr.io/ente-io/镜像路径迁移、Docker Compose 2.30+ 版本要求，以及升级前后ENTE_API_ORIGIN与museum.yaml中数据库、对象存储、apps端点等配置的一致性。

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Ente 自托管服务器升级指南：Quickstart / Docker Compose / 手动部署三种方式详解