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/enteEnte 已将 GitHub 组织从ente-io更名为ente。虽然大部分 Web 链接仍然会重定向到新地址但GitHub Container RegistryGHCR不会为重命名后的路径做重定向因此预构建镜像的位置已经发生了迁移。旧路径已失效新路径ghcr.io/ente-io/serverghcr.io/ente/serverghcr.io/ente-io/webghcr.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 -ddocker compose pull从 GHCR 拉取ghcr.io/ente/server与ghcr.io/ente/web的最新镜像docker compose up -d以新镜像重建并后台启动全部服务museum、socat、postgres、minio、web。升级后释放磁盘空间[!TIP] 可以通过删除旧容器曾经使用的旧版镜像来释放一些磁盘空间docker image prunedocker image prune会删除所有不再被任何容器引用的悬空镜像dangling images。如果希望更彻底地清理例如删除旧版本的标签镜像可以配合docker image prune -a但请确认没有正在运行的容器依赖这些镜像。Quickstart 集群的组成升级前需了解通过server/quickstart.sh生成的compose.yaml包含以下服务见 server/quickstart.sh服务镜像宿主端口用途museumghcr.io/ente/server8080Ente 的 Go 服务端Museum/APIsocatalpine/socat—将容器内localhost:3200转发到 minio 容器webghcr.io/ente/web3000、3002其余默认注释Photos 与 Albums Web 应用postgrespostgres:15—数据库不对外暴露端口miniominio/minio3200本地对象存储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包括重建 MuseumEnte 的服务端# 进入 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_ENDPOINThttp://localhost:8080。如果 Museum 端点在升级前后发生了变化这里必须同步更新并重新构建 Web 应用。升级前后必须核对的环境与配置要点无论采用哪种升级方式以下要点都值得在升级前核对详见 env-var.md 与 config.md环境变量服务环境变量描述默认值webENTE_API_ORIGINNEXT_PUBLIC_ENTE_ENDPOINT的别名即 Museum API 端点http://localhost:8080postgresPOSTGRES_USERPostgreSQL 用户名pguserpostgresPOSTGRES_DB数据库名ente_dbpostgresPOSTGRES_PASSWORD数据库密码Quickstart 随机生成minioMINIO_ROOT_USERMinIO 用户名Quickstart 随机生成minioMINIO_ROOT_PASSWORDMinIO 密码Quickstart 随机生成在 Quickstart 生成的compose.yaml中Web 容器通过ENTE_API_ORIGIN: http://localhost:8080指向 Museum如果你的 Museum 地址是自定义的如配置了域名升级后需确保该值仍然正确。端口一览服务类型宿主端口Museum服务端8080Ente PhotosWeb3000Ente AccountsWeb3001Ente AlbumsWeb3002Ente AuthWeb3003Ente CastWeb3004Ente Public LockerWeb3005Ente EmbedWeb3006Ente Paste独立部署时Web3008Ente LockerWeb3009Ente MemoriesWeb3010MinIOS33200注意Quickstart 生成的compose.yaml默认只暴露3000Photos与3002Albums其余端口以注释形式存在需要时取消注释即可见 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中对象存储默认使用本地 MinIOare_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.30Ente 要求Docker Compose 版本 2.30 或更高并且只支持docker compose子命令形式docker-compose连字符版本已不再受支持见 requirements.md。Quickstart 脚本在运行时会显式检查 Compose 版本低于 2.30 会直接报错退出见 server/quickstart.shERROR: 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确认所有服务均为Uphealthy状态。访问 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报deniedCompose 文件仍引用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.mdgit reset --hard main后本地改动丢失升级前未 stash。手动部署升级前务必git stash或提交本地修改更多排查资源Docker 相关问题troubleshooting/docker.md其他疑难杂症troubleshooting/misc.mdCLI 相关问题troubleshooting/cli.md总结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手动部署无 Dockergit 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），仅供参考