Docker部署Hammer自托管同步服务器:完整指南,5分钟搭建私有写作云
Docker部署Hammer自托管同步服务器:完整指南,5分钟搭建私有写作云
Hammer是一款面向小说创作的开源写作工具,而通过Docker部署Hammer同步服务器,你可以在自己的机器上快速搭建一套自托管的私有写作云。本文以新手视角,带你从零完成Hammer同步服务器的Docker部署:无需外部数据库、只需一个数据卷,两条命令即可让服务器跑起来,再配置好HTTPS,手机、平板、电脑上的写作内容就能全部安全地同步到自己的私有服务器中。
为什么需要Hammer自托管同步服务器?
Hammer支持跨设备同步:在手机上记录的灵感、在电脑上写完的章节,都可以通过同步服务器自动保持一致。默认情况下,你也可以使用官方服务器;但如果你希望写作数据完全掌握在自己手中,自托管同步服务器就是更好的选择:
- 🔒 数据隐私:小说草稿、人物小传等敏感内容只存放在你自己的硬盘上;
- 🌐 低延迟同步:服务器在家或在内网,多设备同步速度更快;
- 🧩 开箱即用:Docker镜像内置嵌入式PostgreSQL,不需要单独安装任何数据库。
部署完成并连接客户端后,你的Hammer会看到这样的项目数据面板:
部署前的准备:一台服务器就够了
整个部署过程对硬件几乎零要求:
- 一台可以联网的Linux机器(树莓派、家用NAS、云服务器均可);
- 已安装Docker和Docker Compose;
- (可选)一个域名,用于后续配置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
这两条命令会做三件事:
- 拉取官方预构建的
hammer-editor/server:latest镜像; - 创建
hammer-data数据卷,所有持久化数据(数据库、缓存、配置)都保存在这里; - 以普通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的项目选择界面会列出你的所有作品:
配置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等正规证书。
创建管理员账号并连接客户端
- 打开任意一台设备上的Hammer客户端(Android、iOS、桌面端均可);
- 输入你服务器的HTTPS地址,创建账号;
- 第一个创建的账号自动成为管理员账号,请务必用自己的主账号先注册。
密码规则很简单:8~64个字符即可,没有复杂度要求。
之后客户端里的编辑、笔记、百科全书等内容都会自动与你的私有服务器同步:
在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。
现在,把服务器地址填进你的手机客户端,开始享受完全属于自己的私有写作云吧 ✍️



