victorrds/etebase

Etebase Server Docker镜像

Etebase Server（又称Etesync 2.0）的Docker镜像，基于Tom Hacohen的https://github.com/etesync/server%E4%BB%93%E5%BA%93%E6%9E%84%E5%BB%BA%EF%BC%8C%E6%8F%90%E4%BE%9B%E5%AE%89%E5%85%A8%E7%9A%84%E7%AB%AF%E5%88%B0%E7%AB%AF%E5%8A%A0%E5%AF%86%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5%E6%9C%8D%E5%8A%A1%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。

使用方法

基本运行命令

bash
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：超级用户密码（可选，未设置则自动生成）；
  • SUPER_EMAIL：超级用户***（可选）。

与etebase-server.ini相关的设置

• ETEBASE_EASY_CONFIG_PATH：配置文件路径，默认：/data/etebase-server.ini；
• MEDIA_ROOT²：用户数据存储路径，默认：/data/media（https://github.com/etesync/server#data-locations-and-backups%EF%BC%89%EF%BC%9B
• DB_ENGINE：数据库引擎，支持sqlite（默认）和postgres；
• ALLOWED_HOSTS²：允许的主机列表（逗号分隔），用于设置Django的CSRF_TRUSTED_ORIGINS，默认：localhost,127.0.0.1,[::1]（详见https://github.com/etesync/server#183%EF%BC%89%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集成（高级用法）

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

详情参见https://github.com/etesync/server/commit/fac36aae***fdc5ae4874065a3528626ef68%E3%80%82

Docker Secrets

可在环境变量后添加_FILE后缀，从容器内文件加载敏感信息（如Docker secrets）。支持的变量：DB_ENGINE、DATABASE_NAME、DATABASE_USER、DATABASE_PASSWORD、SUPER_USER、SUPER_PASS。

示例：

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

端口

镜像暴露3735/TCP端口。

问题与反馈

• 问题讨论：https://github.com/victor-rds/docker-etebase/discussions
• 缺陷报告：https://github.com/victor-rds/docker-etebase/issues

构建方法

选择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_系列变量（SUPER_USER、SUPER_PASS、SUPER_EMAIL），首次运行时自动创建超级用户。

方法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

需挂载有效证书，默认查找/certs/crt.pem和/certs/key.pem。可通过X509_CRT和X509_KEY环境变量修改路径。

故障排除：CSRF验证失败

Etebase服务器升级至Django 4.2+后，需正确配置CSRF_TRUSTED_ORIGINS。解决方法：在etebase-server.ini的[allowed_hosts] section添加服务器域名/IP。

新安装时，可通过ALLOWED_HOSTS环境变量生成配置。示例：

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

详情参见https://github.com/etesync/server#183%E3%80%82

弃用通知：arm/v7镜像

自0.14.0版本起，不再支持arm/v7架构的Docker镜像。因Etebase Server依赖在arm/v7架构上构建困难，后续版本不再提供更新。

版本不兼容警告

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