victorrds/etesync

Etebase Server Docker镜像

Docker镜像用于Etebase Server（也称为EteSync 2.0），基于https://github.com/tasn%E7%9A%84https://github.com/etesync/server%E4%BB%93%E5%BA%93%E6%9E%84%E5%BB%BA%E3%80%82

标签

以下标签基于最新Python镜像和最新版本的Etebase Server构建：

• latest https://github.com/victor-rds/docker-etebase/blob/master/tags/base/Dockerfile
• slim https://github.com/victor-rds/docker-etebase/blob/master/tags/slim/Dockerfile
• alpine https://github.com/victor-rds/docker-etebase/blob/master/tags/alpine/Dockerfile

发布版本以带版本号的标签提供，例如：X.Y.Z 或 X.Y.Z-type。

用法

docker run -d -e SUPER_USER=admin -p 80:3735 -v /path/on/host:/data victorrds/etesync

创建一个使用HTTP协议运行Etebase的容器。

更多使用docker-compose的示例可在此处查看。

目录结构与数据持久化

所有Etebase镜像变体共享相同的文件夹结构：

/etebase

包含Etebase Server源代码，请勿修改或挂载此文件夹。

/data

默认情况下，此目录是存储所有用户数据和服务器配置的卷：

• /data/etebase-server.ini：服务器配置文件，位置可通过ETEBASE_EASY_CONFIG_PATH环境变量更改；
• /data/media：用户数据存储目录，虽可更改¹，但不建议；
• /data/secret.txt：包含Django SECRET_KEY的文件，位置可更改¹；
• /data/db.sqlite3：SQLite数据库文件（若选择SQLite），位置可更改¹。

¹ 所有位置在etebase-server.ini文件中设置，或首次运行时通过环境变量设置。

/srv/etebase

包含需与反向代理（如nginx）共享的静态文件，当使用uwsgi或asgi协议时，/entrypoint.sh会检查并更新或重建这些文件（若不存在）。

用户与权限

默认情况下，容器以用户和组etebase运行，数值ID均为373。若将上述目录挂载到宿主而非使用Docker卷，有两种处理方式：

1. 目录需设置正确权限，例如：

   console
   $ chown -vR 373:373 /host/data/path
   changed ownership of '/host/data/path' from user:group to 373:373
   $ docker run -v /host/data/path:/data victorrds/etebase
   

2. 更改容器运行用户：

   console
   $ stat -c '%u:%g' /host/data/path
   1000:1000
   $ docker run -u 1000:1000 -v /host/data/path:/data victorrds/etebase
   

设置与自定义

Etebase的可用设置在/data/etebase-server.ini文件中配置。若文件不存在，/entrypoint.sh将基于以下环境变量生成该文件。

环境变量

• SERVER：定义容器如何提供应用服务，选项包括：
  • uvicorn：使用uvicorn（ASGI服务器，支持HTTP/1.1和WebSocket），无SSL，需配合反向代理（如nginx、traefik）使用。别名：http、http-socket、asgi；
  • uvicorn-https：同上，但启用SSL/TLS，需挂载证书。别名：https；
  • 旧版本支持uwsgi、daphne和Django-server，现已不再支持（详见https://github.com/victor-rds/docker-etebase/issues/103%EF%BC%89%EF%BC%9B
• DEBUG：详细模式，提供/entrypoint.sh的额外日志，不影响Etebase服务器输出；
• SHELL_DEBUG：以set -x运行/entrypoint.sh，用于调试；
• AUTO_UPDATE：容器启动时自动触发数据库更新/迁移，默认：false；
• SUPER_USER：Django超级用户名（仅在无现有数据库时使用）；
  • SUPER_PASS：Django超级用户密码（可选，未设置则自动生成）；
  • SUPER_EMAIL：Django超级用户***（可选）。

与etebase-server.ini配置文件相关的变量

• ETEBASE_EASY_CONFIG_PATH：配置文件位置，默认：/data/etebase-server.ini；
• MEDIA_ROOT²：用户数据存储路径。https://github.com/etesync/server#data-locations-and-backups 默认：/data/media；
• DB_ENGINE：数据库引擎，当前仅支持sqlite（默认）和postgres；
• ALLOWED_HOSTS²：允许的主机列表，需为逗号分隔的有效域名/IP，用于设置Django的CSRF_TRUSTED_ORIGINS。必须包含访问服务器的域名（详见https://github.com/etesync/server#183%EF%BC%89%E3%80%82%E9%BB%98%E8%AE%A4%EF%BC%9A%60localhost,127.0.0.1,%5B::1%5D%60%EF%BC%9B
• SECRET_FILE²：Django SECRET_KEY存储文件路径，若不存在则自动生成。默认：/data/secret.txt；
• AUTO_SIGNUP：启用自动注册，默认：false；
• LANGUAGE_CODE：Django语言代码，默认：en-us；
• TIME_ZONE：时区，默认UTC，需为有效的tz数据库名称（有效名称见<[***]>）；
• DEBUG_DJANGO²：启用Django调试模式，生产环境不推荐，默认：false；
• REDIS_URI：Redis URI（可选）。

² 更多详情请参考https://github.com/etesync/server#configuration%E3%80%82

若DB_ENGINE设为**sqlite**：

• DATABASE_NAME：数据库文件路径，默认：/data/db.sqlite3。

若DB_ENGINE设为**postgres**，可使用以下变量（仅列出默认值）：

• DATABASE_NAME：etebase；
• DATABASE_USER：默认与DATABASE_NAME相同；
• DATABASE_PASSWORD：默认与DATABASE_USER相同；
• DATABASE_HOST：database；
• DATABASE_PORT：5432。

LDAP集成（高级用法，详情参考https://github.com/etesync/server/commit/fac36aae***fdc5ae4874065a3528626ef68%EF%BC%89%EF%BC%9A

• LDAP_SERVER：LDAP服务器URL；
• LDAP_BINDDN：绑定用户的DN；
• LDAP_BIND_PW：绑定用户密码；
• LDAP_FILTER：LDAP过滤查询（%%s将替换为用户名）；
• LDAP_SEARCH_BASE：搜索基；
• LDAP_CACHE_TTL：缓存TTL（小时，可选）。

Docker Secrets

作为通过环境变量传递敏感信息的替代方式，可在部分环境变量后追加_FILE，使初始化脚本从容器内文件加载值（适用于Docker Secrets，存储在/run/secrets/<secret_name>）。例如：

bash
docker run -d --name etebase \
 -e DB_ENGINE=postgres \
 -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres-passwd \
 victorrds/etebase

目前支持此方式的变量：DB_ENGINE、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD、SUPER_USER、SUPER_PASS。

端口

镜像暴露3735/TCP端口。

问题与反馈

问题咨询请使用https://github.com/victor-rds/docker-etebase/discussions%EF%BC%9B 错误报告请提交至仓库https://github.com/victor-rds/docker-etebase/issues%E3%80%82

构建方法

选择Dockerfile构建镜像：

bash
docker build -f tags/alpine/Dockerfile -t etebase:alpine .

默认基于Etebase master分支构建。如需基于特定版本，设置ETE_VERSION构建参数：

bash
docker build --build-arg ETE_VERSION=v0.5.3 -f tags/base/Dockerfile -t etebase:dev .

高级用法

创建超级用户

方法1：首次运行时使用环境变量

首次运行时设置SUPER_系列变量，将在数据库准备就绪后创建超级用户。

方法2：Python Shell

数据库就绪后，可随时通过以下命令创建超级用户（按提示操作）：

bash
docker exec -it {container_name} python manage.py createsuperuser

升级应用与数据库

若未设置AUTO_UPDATE，可手动更新：

bash
docker exec -it {container_name} python manage.py migrate

使用带SSL/TLS的Uvicorn

需挂载有效证书。默认Etebase查找/certs/crt.pem和/certs/key.pem，若更改位置，需通过X509_CRT和X509_KEY环境变量指定。

故障排除：CSRF验证失败

Etebase服务器已升级至Django 4.2+，需设置有效的CSRF_TRUSTED_ORIGINS。解决方法：将服务器域名/IP添加到etebase-server.ini的[allowed_hosts] section。

若为新安装且无ini文件，可通过ALLOWED_HOSTS环境变量生成正确的ini文件。

示例：

ini
[allowed_hosts]
allowed_host1 = example.com
allowed_host2 = api.example.com
allowed_host3 = 10.0.0.1
; 支持通配符，但单独*无效
allowed_host4 = *.etebase.example.com

更多详情见PR：https://github.com/etesync/server#183%E3%80%82

弃用通知：arm/v7镜像

自0.14.0版本起，不再支持arm/v7架构的Docker镜像。因Etebase Server的许多依赖项在arm/v7架构上使用默认Python基础镜像构建变得困难或无法实现。

版本不兼容警告

Etesync 1.0与Etebase（Etesync 2.0）的数据库和服务器不兼容。由于软件的端到端加密特性和结构变化，无法在未知用户密钥的情况下迁移数据。

迁移数据需创建新实例和数据库，同时运行新旧服务器，通过Web客户端或移动应用迁移数据。所有用户迁移完成后，可关闭旧服务器。

新镜像存在破坏性变更，entrypoint.sh会在修改前检查数据库兼容性。

Etesync 1.0镜像通过legacy标签提供，基础镜像已过时且不再维护：

• legacy https://github.com/victor-rds/docker-etesync-server/blob/legacy/tags/base/Dockerfile
• legacy-slim https://github.com/victor-rds/docker-etesync-server/blob/legacy/tags/slim/Dockerfile
• legacy-alpine https://github.com/victor-rds/docker-etesync-server/blob/legacy/tags/alpine/Dockerfile