Docker部署Hammer自托管同步服务器:完整指南,5分钟搭建私有写作云

原创2026-10-26 19:29:291,820 阅读

Docker部署Hammer自托管同步服务器:完整指南,5分钟搭建私有写作云

Hammer是一款面向小说创作的开源写作工具,而通过Docker部署Hammer同步服务器,你可以在自己的机器上快速搭建一套自托管的私有写作云。本文以新手视角,带你从零完成Hammer同步服务器的Docker部署:无需外部数据库、只需一个数据卷,两条命令即可让服务器跑起来,再配置好HTTPS,手机、平板、电脑上的写作内容就能全部安全地同步到自己的私有服务器中。

为什么需要Hammer自托管同步服务器?

Hammer支持跨设备同步:在手机上记录的灵感、在电脑上写完的章节,都可以通过同步服务器自动保持一致。默认情况下,你也可以使用官方服务器;但如果你希望写作数据完全掌握在自己手中,自托管同步服务器就是更好的选择:

  • 🔒 数据隐私:小说草稿、人物小传等敏感内容只存放在你自己的硬盘上;
  • 🌐 低延迟同步:服务器在家或在内网,多设备同步速度更快;
  • 🧩 开箱即用:Docker镜像内置嵌入式PostgreSQL,不需要单独安装任何数据库。

部署完成并连接客户端后,你的Hammer会看到这样的项目数据面板:

Hammer同步服务器连接后的项目结构面板,展示章节字数与人物统计

部署前的准备:一台服务器就够了

整个部署过程对硬件几乎零要求:

  1. 一台可以联网的Linux机器(树莓派、家用NAS、云服务器均可);
  2. 已安装Docker和Docker Compose;
  3. (可选)一个域名,用于后续配置HTTPS。

Hammer的官方Docker文件都在仓库的 docker/ 目录下:

文件 作用
docker/Dockerfile 运行时镜像,打包预编译的服务端程序
docker/docker-compose.yml 一键式编排,自带数据卷
docker/config.example.toml 配置文件模板,所有选项均可选

完整的官方Docker指南见 docs/HOW-TO-RUN-A-SERVER-DOCKER.md,本文是它的精简版。

5分钟快速部署:两条命令启动服务器

进入仓库的 docker 目录,执行:

cd docker
docker compose up -d

这两条命令会做三件事:

  1. 拉取官方预构建的 hammer-editor/server:latest 镜像;
  2. 创建 hammer-data 数据卷,所有持久化数据(数据库、缓存、配置)都保存在这里;
  3. 以普通HTTP方式在 127.0.0.1:8080 启动服务。

如果你不想用Compose,也可以用单条命令手动运行:

docker run -d --name hammer-server \
  -p 127.0.0.1:8080:8080 \
  -v hammer-data:/data \
  ghcr.io/darkrock-studios/hammer-editor/server:latest

执行完成后,可以用以下命令确认服务已正常启动:

docker ps          # 查看容器是否在运行
docker logs hammer-server   # 查看启动日志

💡 注意到端口只绑定到 127.0.0.1 了吗?这是刻意设计:容器内是明文HTTP,直接暴露到公网等于把密码和同步流量裸奔。后面我们会用HTTPS代理解决对外访问。

部署完成并连接客户端后,Hammer的项目选择界面会列出你的所有作品:

Hammer项目选择界面,显示已连接同步服务器后的小说项目列表

配置HTTPS:客户端连接的必要一步

这是新手最容易卡住的一步:Hammer客户端只支持HTTPS,无法直接连接容器的HTTP端口。有两条官方支持的路线:

方案一:反向代理(推荐)

用Nginx、Caddy或Traefik终结TLS,再转发到容器的8080端口。这是最省心的做法,证书续期也完全由代理侧管理。

在 config.toml 中加上一行:

trustProxyForwarding = true

这行配置让Hammer从 X-Forwarded-For 头读取真实客户端IP,保证登录限流和审计日志记录的是真实地址,而不是代理的同一个地址。

方案二:让Hammer自己终结TLS

挂载证书目录并开放443端口:

    ports:
      - "443:443"
    volumes:
      - hammer-data:/data
      - /etc/letsencrypt:/certs:ro
sslPort = 443

[sslCert]
certChainPath = "/certs/live/hammer.example.com/fullchain.pem"
privateKeyPath = "/certs/live/hammer.example.com/privkey.pem"

⚠️ 两个重要提醒:

  • 服务器只在启动时读取证书,续期后必须 docker restart hammer-server(可以在certbot里配置 deploy_hook 自动完成),否则大约90天后所有客户端会因证书过期而停止同步;
  • 自签名证书不被支持,移动端只信任系统CA证书,请使用Let's Encrypt等正规证书。

创建管理员账号并连接客户端

  1. 打开任意一台设备上的Hammer客户端(Android、iOS、桌面端均可);
  2. 输入你服务器的HTTPS地址,创建账号;
  3. 第一个创建的账号自动成为管理员账号,请务必用自己的主账号先注册。

密码规则很简单:8~64个字符即可,没有复杂度要求。

之后客户端里的编辑、笔记、百科全书等内容都会自动与你的私有服务器同步:

Hammer场景编辑器界面,章节正文与元数据面板通过同步服务器跨设备共享

在Android平板上,笔记卡片等数据同样会保持多端一致:

Hammer Android平板端笔记界面,展示同步服务器管理下的写作笔记卡片

关键配置详解:config.toml 与时区

服务器会自动加载数据目录中的 config.toml(容器内路径 /data/hammer_data/config.toml),无需任何启动参数。以 docker/config.example.toml 为起点,最常用的是这两项:

# 公开展示给用户的服务器名称
host = "hammer.example.com"

# 邮件链接使用的对外地址(走反向代理时必设)
publicUrl = "https://hammer.example.com"

时区方面,容器默认运行在UTC,日志和时间戳也按UTC显示。可以在Compose文件旁的 .env 文件里写:

TZ=Asia/Shanghai

或直接在 config.toml 中设置(优先级更高):

timezone = "Asia/Shanghai"

⚠️ 两个新手常见的坑:

  • 不要在Docker里设置 bindHosts。官方普通服务器指南建议反向代理下绑定 127.0.0.1,但容器内这会让发布端口指向一个没人监听的地址——服务显示健康但完全无法访问。暴露控制请用 HAMMER_HTTP_BIND 环境变量在宿主机层面做;
  • 配置文件有语法错误时,容器会直接启动失败,请第一时间查看 docker logs。

进阶:外接PostgreSQL数据库

默认使用容器内嵌的PostgreSQL,适合绝大多数自托管场景。如果确实需要外接数据库,在 config.toml 中取消 docker/config.example.toml 里 [storage] 段的注释,并在 docker/docker-compose.yml 中放开被注释的 postgres 服务即可,空数据库会在首次连接时自动建表。注意 useSsl 默认是 true,连接不带TLS的本地postgres时务必设为 false。

数据与备份:一个卷搞定

所有持久化数据都在 /data 卷下:

/data/hammer_data/
  pgdata/                 内嵌PostgreSQL数据
  cache/                  可再生的渲染缓存
  config.toml             你的配置(如放在这里)
  server.keyring.json     加密密钥环(如启用了加密)

因此备份服务器 = 备份这个卷:

docker run --rm -v hammer-data:/data \
  alpine tar czf /tmp/hammer-backup-$(date +%F).tar.gz -C /data .

常见问题排查(FAQ)

🔌 客户端提示"无法建立安全连接"? 说明它连到了明文HTTP端口。检查是否已经配置了HTTPS(反向代理或证书),这是最常见的部署问题。

🔑 账号创建后登录返回401? 先排除两种容器特有的原因:一是数据卷被重建过(执行过 docker compose down -v),账号已不存在;二是登录被限流——限流按来源地址每分钟10次,反向代理下所有人共享代理地址,多次尝试会收到 429 而不是 401。

🕐 容器端口如何修改?

HAMMER_HTTP_BIND=0.0.0.0 HAMMER_HTTP_PORT=8090 docker compose up -d

仅在确认没有不受信任的流量能到达宿主机时才把绑定地址改为 0.0.0.0。

🔍 镜像如何自己构建? 镜像打包的是预编译分发版(因为服务端与Android客户端共享模块,从源码构建需要Android SDK),在仓库根目录执行 ./gradlew :server:installDist 后再 docker build -f docker/Dockerfile 即可。

写在最后

回顾一下本次部署的核心路径:两条命令启动容器 → 反向代理加上HTTPS → 客户端注册管理员账号 → 备份 /data 卷。得益于内嵌数据库和单卷设计,Hammer同步服务器是目前对个人自托管最友好的写作同步方案之一。更多细节(用户白名单、邮件、加密存储等)请阅读官方文档 docs/HOW-TO-RUN-A-SERVER.md 与 docs/HOW-TO-RUN-A-SERVER-DOCKER.md。

现在,把服务器地址填进你的手机客户端,开始享受完全属于自己的私有写作云吧 ✍️

登录后查看全文
hammer-editor