1. 部署前必须想清楚的三件事1.1 Haptic是什么为什么值得本地部署Haptic是一款面向个人知识管理场景的笔记管理工具它跟我之前用过的很多笔记软件不一样的地方在于它把数据所有权真正还给了用户。你部署在自己机器上笔记数据就只存在于你的硬盘里不经过任何第三方服务器。对于经常写技术笔记、记实验记录、甚至存一些不便上传到公有云的工作文档的人这个点本身就足够有吸引力。另外Haptic走的是“服务端任意浏览器”的逻辑部署完成之后你不需要再装任何客户端电脑手机只要能开浏览器就能访问。这个形态跟很多自托管知识库工具很像数据在你自己手里界面和交互完全可控还能通过WebDAV协议跟其他生态工具打通。我从实际体验的角度说一句本地部署Haptic最明显的收益不是“省钱”而是可控性。你可以自己决定什么时候升级、怎么备份、开放给谁用而不是被SaaS产品的路线图绑架。如果只是想随便记点东西公有云笔记完全够用但如果你把它当作个人知识库的基座未来还想基于这些数据做一些自动化处理、二次开发那自托管几乎是唯一出路。1.2 环境准备这套方案需要什么先说我这次部署使用的环境组合你可以根据自己的实际情况替换操作系统Ubuntu 22.04 LTSDebian系应该都没问题运行环境Docker Docker Compose插件域名一个已经备案、能正常解析的域名如果是纯IP访问后面会告诉你有什么坑公网环境宽带拨号获取的是动态IP所以需要动态DNS配合其他一台能7x24小时开机的机器哪怕是淘汰下来的旧笔记本都行为什么选Docker而不是直接裸机装我在这个问题上踩过不少次坑。笔记管理工具牵扯到的组件其实不少数据库、静态资源服务、Web服务、可能还有全文索引。如果直接在宿主机上安装等你想升级版本或者迁移服务器的时候依赖冲突能折磨到你怀疑人生。Docker把这些东西全部隔离封装升级就是拉新镜像、起新容器回滚就是改一个镜像标签。还有一个很多人忽略的点内存和磁盘规划。我用的机器是4GB内存跑Haptic加一两个辅助容器绰绰有余。磁盘上除了系统占用之外最好给笔记数据单独分一个区或者至少单独建一个目录后续做快照备份会比较方便。我给Haptic数据目录分配的是50GB说实话对纯文本笔记来说非常充裕但如果你的使用习惯是往笔记里塞大量截图、PDF附件容量就还需要再往上提。1.3 外部访问方案选型别急着暴露到公网本地部署完成之后最核心的问题就是外部访问。什么叫“外部访问”就是你离开家、离开办公室在任意网络环境下还能打开自己的笔记服务。先说我的结论不要直接把服务端口映射到公网。之前见过太多人图省事把服务的8080端口直接映射到路由器的WAN口然后去公共WiFi环境下访问。这样做风险非常高因为像Haptic这类面向个人使用的服务通常自身的安全设计不会考虑公网恶意扫描的情况弱口令、未授权访问这一类漏洞一旦被扫出来等于把笔记数据直接送给陌生人。常见的可行方案有四类我在下面的章节会分开讲公网IP 路由器端口映射 动态DNS 反向代理内网穿透工具frp、ngrok等异地组网工具Tailscale等PaaS平台的隧道Cloudflare Tunnel等这几种方案没有绝对的优劣取决于你自己的网络环境和动手能力。我这次选择的方案是“公网IP 动态DNS Nginx反向代理 HTTPS证书”整套做下来体验最接近访问一个正常网站后面章节会详细拆解步骤。2. Docker部署Haptic一次跑通的完整步骤2.1 目录规划与docker-compose配置动手之前先把目录结构想清楚。我的习惯是统一把自托管应用放在/opt下面每个应用一个文件夹数据文件和配置文件的权限单独管控sudo mkdir -p /opt/haptic/data sudo mkdir -p /opt/haptic/config sudo chown -R $USER:$USER /opt/haptic这样一个简单的动作就能避免后面容器运行时遇到权限不足的问题。很多人第一次部署Docker应用报错“permission denied”八成就是宿主机目录的属主跟容器内用户对不上。然后创建docker-compose.yml。这里我直接给出我实际在用的配置关键参数后面逐个解释version: 3 services: haptic: image: haptic/haptic:latest container_name: haptic restart: always ports: - 127.0.0.1:8080:80 volumes: - /opt/haptic/data:/app/data - /opt/haptic/config:/app/config environment: - TZAsia/Shanghai - HAPTIC_DATA_DIR/app/data - HAPTIC_CONFIG_DIR/app/config - HAPTIC_SERVER_PORT80 logging: driver: json-file options: max-size: 10m max-file: 3注意一个细节ports我把宿主机端口绑在了127.0.0.1:8080而不是0.0.0.0:8080。这两者差别很大绑定在回环地址上宿主机外面的任何设备都无法直接访问这个端口只有本机进程能通过8080端口连过去。这意味着即使有人扫描你服务器IP的所有端口也看不到Haptic服务安全性直接提高一个等级。外部访问由后面的反向代理统一接管从80/443端口进来。2.2 环境变量和参数说明这里解释几个关键配置项的意图不是每个都用默认值就行restart: always容器异常退出后Docker会自动把它拉起来不用写systemd定时任务去检查进程状态。TZAsia/Shanghai时区必须显式指定否则容器默认使用UTC时间你笔记里的时间戳会比北京时间慢8小时。HAPTIC_DATA_DIR和HAPTIC_CONFIG_DIR指定数据目录和配置目录把它们映射到宿主机才能实现容器重建之后数据不丢。logging块限制日志文件大小和数量。这个配置是血泪教训之前跑某个应用没限制日志大小半年后磁盘飘红排查了半天发现是几百兆的JSON日志。启动服务就两条命令cd /opt/haptic docker compose up -d docker compose logs -f日志里出现类似“server is listening on port 80”的输出就说明服务起来了。然后本机验证一下curl http://127.0.0.1:8080能看到网页的HTML输出部署成功了第一步。2.3 初始化配置创建管理员账户Haptic第一次访问时会引导你创建管理员账户。这一步要注意管理员账户的用户名和密码不要跟任何已有网站的账户密码重复因为你的服务暴露在公网上字典攻击是最常见的破解手段弱密码在这个场景下等于裸奔。初始化完成之后建议立刻做两件事一是修改默认配置里的注册开关。很多笔记工具默认允许新用户注册但你自己用的话没必要开放注册找到设置项把“允许注册”关掉防止陌生人拿到你的服务地址后给自己开账号。二是配置数据备份。Haptic的数据目录里主要是SQLite数据库文件和附件备份策略最简单的方案是写一个cron定时任务每天凌晨把整个/opt/haptic/data目录打包然后通过rsync或者rclone同步到另一台机器或者对象存储上。备份脚本我后面章节会给出。3. 外部访问的几种路径以及我为什么这样选3.1 四类方案横向对比外部访问从技术路径上看无外乎两条思路暴露型和组网型。暴露型方案把你的服务通过一个公网可访问的入口暴露出去访问者通过域名或者IP直接访问。典型代表是路由器端口映射、frp内网穿透、Cloudflare Tunnel。组网型方案你的设备和服务之间建立一个虚拟的私有网络只有在这个网络里的设备才能访问服务。典型代表是Tailscale、ZeroTier。我梳理了一个对比表格方便你快速判断自己适合哪种方案上手难度访问体验安全性适用场景公网IP端口映射反代中等最好较高配置得当的话有公网IPv4或IPv6愿意折腾frp内网穿透中等好中高没有公网IP但有云服务器Cloudflare Tunnel低好高有域名不想维护入口服务器Tailscale组网极低好高只有自己用不考虑多人访问简单解释一下原理层面的差异。路由器端口映射本质是NAT穿透把公网特定端口的流量转发到内网机器的特定端口它做的是一件很纯粹的事帮你“开门”。但开了门之后门后面有没有人守着反向代理、守门的人负不负责HTTPS、访问控制决定了这套方案安不安全。frp的原理类似只不过“开门”这件事发生在一台有公网IP的云服务器上你内网机器通过长连接告诉云服务器“帮我开个口子”流量经过云服务器中转进入内网。它的好处是不要求你有公网IP坏处是流量多了一道转发延迟会高一些。Tailscale则是完全不同的思路它不暴露任何端口而是在你的设备之间组建一个加密的虚拟局域网只有加入这个网络的设备才能通过虚拟IP访问你的Haptic服务。这个方案对个人使用来说体验极好但如果你想让家人朋友不装任何客户端就直接访问你的笔记就行不通了。我最终选择的是“公网IPNginx反向代理”主要原因有三个一是体验最接近普通网站浏览器直接输域名就能访问不用在访问端装任何东西二是IPv6减少了NAT转换环节延迟更低三是我有自建反向代理和证书管理的经验配置成本对我来说最低。3.2 公网IP 动态DNS Nginx反代的完整落地这套方案四个组成部分各司其职公网IP给外部访问提供一个“入口地址”动态DNS把域名实时解析到不断变化的家庭宽带IP上Nginx反向代理统一接管外部流量转发给内网的Haptic服务HTTPS证书加密客户端和服务器之间的传输数据第一步是确认你确实有公网IP。中国电信/联通/移动的宽带情况不太一样确认方法很简单在路由器管理页面看WAN口IP然后拿手机流量访问这个IP如果能看到路由器登录页或者服务说明是公网IP。如果看不到一般是运营商做了NAT你需要打客服电话申请公网IP。这一步如果搞不定就直接换frp或者Tailscale方案。第二步是配置动态DNS。宽带IP会定期变化所以需要一个机制让域名始终解析到最新的IP。我用的是ddns-go这个开源工具它支持国内多个域名服务商。部署同样放在Docker里ddns-go: image: jeessy/ddns-go container_name: ddns-go restart: always network_mode: host volumes: - /opt/ddns-go/config:/root启动之后通过宿主机9876端口打开管理界面填入DNS服务商的API密钥选择要解析的域名它会每隔几分钟检测一次本机公网IP变了就自动更新解析记录。第三步是路由器端口映射。登录路由器管理页面找到“端口映射”或“虚拟服务器”设置新建一条规则外部端口443转发到内网机器IP的443端口外部端口80转发到内网机器IP的80端口。这一步其实把“门”开到了反向代理上而不是直接开到Haptic服务上——多这一层隔离安全性完全不同。第四步是Nginx反向代理配置。因为我选择只通过域名访问所以把Haptic服务绑定在了notes.example.com这个子域名上。配置很简单server { listen 80; server_name notes.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name notes.example.com; ssl_certificate /etc/letsencrypt/live/notes.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/notes.example.com/privkey.pem; client_max_body_size 50m; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 300s; } }逐行解释几个关键点client_max_body_size 50m限制上传文件大小。如果你经常往笔记里贴图片、附件这个值不设置的话默认只有1MB传大点的截图直接413。proxy_set_header X-Forwarded-Proto $scheme告诉后端服务“用户是通过HTTPS访问的”。如果漏掉这个头Haptic可能会因为检测到HTTP请求而自动把页面重定向到HTTP地址导致访问死循环。3.3 HTTPS证书的自动化管理说完反代很自然就得到下一个问题证书从哪来用Lets Encrypt签证书用certbot自动续期这已经是约定俗成的操作了。安装和使用很简单sudo apt install certbot -y sudo certbot certonly --standalone -d notes.example.com --email youremail.com --agree-tos --no-eff-email这里有一个经常出问题的地方certonly --standalone要求80端口没有被任何程序占用因为它要临时起一个服务来通过域名验证。如果你Nginx已经在监听80端口certbot启动时会报错“Port 80 already in use”。解决办法是先停掉Nginx再签证书或者直接用--webroot模式或者干脆用certbot --nginx插件让certbot自动完成证书安装和Nginx配置。我在实际使用中用的是certbot的nginx插件模式sudo certbot --nginx -d notes.example.com它会自动检测你的Nginx配置修改SSL相关配置然后自动重载Nginx。续期也完全自动certbot会安装一个systemd定时器每两个月检查一次到期30天内自动续签。4. 公网形态下的安全加固4.1 访问控制不要让服务裸奔在公网当你的Haptic服务真正可以被公网访问之后最先做的不是写笔记而是安全加固。我在这个环节做了下面这些事按优先级排列第一是删除默认admin账户之外的所有账户如果之前开过注册功能先关闭并清理掉所有注册用户只保留自己和管理员。这一步的意义在于缩小攻击面越少入口越难被攻破。第二是配置Fail2ban。Fail2ban会监控Nginx的访问日志发现某个IP在短时间内频繁登录失败就自动把这个IP封禁一段时间。我在/etc/fail2ban/jail.local里给Nginx配置了一个专门的防护规则。这个工具能在自动化攻击面前给你争取大量时间尤其是那些全球扫描端口的bot。第三是开启强制HTTPS和HTTP到HTTPS的301跳转。为什么不让用户用HTTP访问因为HTTP是明文传输你的密码、笔记内容在链路上可以被任何人看见。现在浏览器地址栏上的小锁标志已经是用户对网站安全的最低预期你的自建服务也应该达到这个标准。4.2 备份策略这条防线不能省再说一次备份因为它真的太重要了。本地部署笔记工具最大的风险不是机器故障而是用户对数据安全的盲目自信。我见过不止一个人辛苦搭好了服务记了大半年笔记结果硬盘损坏或者误删数据目录全部笔记付之东流。我现在的备份方案是双重备份#!/bin/bash # 每天凌晨3点执行 BACKUP_DIR/opt/backups/haptic DATE$(date %Y%m%d_%H%M%S) # 1. 数据目录打包 tar czf ${BACKUP_DIR}/haptic_data_${DATE}.tar.gz -C /opt/haptic data config # 2. 保留最近30天备份自动清理旧文件 find ${BACKUP_DIR} -name haptic_data_* -mtime 30 -exec rm -f {} \; # 3. 可选同步到远程存储 # rclone sync ${BACKUP_DIR} remote:haptic-backup然后在crontab里注册0 3 * * * /opt/scripts/backup_haptic.sh这个脚本干了一件很重要的事保留30天的历史版本。如果你哪次笔记内容被误删或者写坏了你至少还能找回30天内的任意一个版本。如果只保留一份最新备份恢复的时候才发现备份本来就是坏的那才是真正的灾难。4.3 反向代理前的访问白名单Haptic本身有登录机制但我在反向代理层又加了一道基础访问控制这属于纵深防御的思路即使Haptic的登录机制被绕过攻击者还要再突破一层代理层的验证才能看到内容。这里我用的是Nginx的auth_basic实现HTTP Basic Authserver { locate / { auth_basic Restricted Access; auth_basic_user_file /etc/nginx/htpasswd_haptic; proxy_pass http://127.0.0.1:8080; } }生成密码文件sudo htpasswd -c /etc/nginx/htpasswd_haptic your_username这会在进入Haptic登录页面前多一道输入账号密码的屏障。实际用起来只是多一次输入密码的操作但能挡掉绝大多数的扫描器和自动化攻击。如果你的部署环境里只有你自己访问这是性价比极高的一道防线。5. 常见问题与排查技巧实录5.1 问题速查表部署和运行过程中肯定会遇到各种各样的问题我把最常见的几类整理成一张速查表方便你对照排查现象可能原因排查方法解决方案外部访问不了本机能访问路由器端口映射没生效检查路由器WAN口IP和映射规则确认映射的是443/80端口指向内网机器IP提示“无法建立安全连接”SSL证书过期或配置错误sudo certbot certificates查看有效期手动更新证书并重载Nginx页面加载出来是乱码字符编码问题查看Nginx日志有没有proxy相关报错确认反向代理配置了proxy_set_header Host上传大文件失败Nginx的client_max_body_size限制查看Nginx error.log在server块中增大该参数手机流量访问很慢家庭宽带上行带宽限制测速确认上行速率压缩图片或换frp中转方案服务运行一段时间后自己挂了Docker容器OOM或者崩溃重启docker logs haptic增加内存限制并开启自动重启5.2 几个容易踩的坑我的现场实录坑一动态DNS解析生效慢。我把ddns-go配置好之后域名解析更新了但手机访问还是旧IP。排查了半天发现是手机系统DNS缓存的问题运营商递归DNS的缓存时间还生效不是服务的问题。解决方案是等几分钟或者切换WiFi/移动网络测试后续可以在域名服务商那边把TTL调低到120秒让缓存时间更短。坑二IPv6的优先级问题。我的域名解析记录里同时有A记录和AAAA记录。在家庭网络环境下很多设备会优先走IPv6但运营商的IPv6路由质量时好时坏导致有时能访问有时又超时。我的解决办法是在Haptic的反向代理配置文件里增加了一个判断总是优先解析到IPv4地址resolver 8.8.8.8 ipv6off;同时如果家里网络支持IPv6但质量不稳定可以在路由器上关闭IPv6的DNS解析强制走IPv4。坑三容器时间不同步导致笔记时间错乱。这个问题前面提过根源是容器默认使用UTC时间。我一开始没配TZ环境变量写了几条笔记之后发现时间差了8个小时。处理办法就是重新设置环境变量重启容器。注意容器重启后SQLite数据库文件也许会有行锁最好先停掉容器再修改配置避免写坏数据库。坑四WebDAV同步的问题。Haptic支持WebDAV协议用于和第三方工具同步但公网环境下如果你没有用HTTPSWebDAV的密码是在明文传输的这是安全隐患。我一开始没注意直接在第三方工具里填了Haptic的WebDAV地址后来打开抓包工具发现密码直接被看到了。公开网络环境务必只使用HTTPS的WebDAV地址并且建议单独建一个低权限的WebDAV专用账户不要把管理员密码填进去。6. 移动端与多设备协作的接入细节6.1 手机浏览器访问的体验优化Haptic本身提供了响应式网页手机浏览器访问会自动适配布局。但在实际操作中我发现几个需要优化的细节。首先是PWA支持。Haptic支持以PWA渐进式Web应用的方式“安装”到手机桌面这样访问体验跟原生App非常接近。我在iOS上实测过通过Safari的“添加到主屏幕”功能生成的图标是一个独立窗口打开不会显示浏览器地址栏。Android端的Chrome也同样支持而且还可以开启离线缓存网络不稳定的时候也能打开之前看过的笔记页面。这个细节让我觉得Haptic对移动端使用场景的考虑比较到位真正在意用户高频、轻量、随时记的需求。其次是移动网络下的加载速度。如果你的家庭宽带上行只有30Mbps而笔记中有大量原图那么在外网环境打开笔记页面时会明显感觉卡顿。我的方案是在反向代理层开启gzip压缩gzip on; gzip_types text/plain application/javascript text/css application/json; gzip_min_length 1024;实测下来笔记列表页面的传输体积能压缩掉60%以上图片虽然压不了但纯文本为主的笔记场景感知提升明显。6.2 多设备间同步的冲突处理用Haptic做了主力笔记工具之后我逐渐养成了在电脑上写长文、在手机上随手记灵感的习惯。多设备协同的工作流带出一个新问题同步冲突。Haptic的同步机制是基于服务端版本的正常情况下不会出现冲突比如你在电脑上编辑笔记A同时在手机上编辑笔记B两条笔记会分别独立保存互不影响。但如果出现以下两种情况就会触发冲突一是在同一台设备上离线编辑了一篇笔记然后又切到另一台设备上在线编辑了同一篇笔记。解决方法是每次编辑前确认笔记已经成功同步到最新版本。二是移动端网络状况不好接口超时之后用户重复点击保存导致同一篇笔记被提交了多次。Haptic在检测到这个情况时会生成一个冲突副本不会丢失任何一方的内容。这个设计我认为是非常稳的比某些云笔记直接覆盖旧版要友好得多。我在实际使用中总结了三条减少冲突的经验手机端记录碎片想法时尽量在新的空白笔记里写不要反复打开同一篇旧笔记追加重写。长时间运行的浏览器标签页的笔记内容可能过期保存前要刷新页面拿到最新内容。如果实在需要离线编辑建议编辑完成后立刻回到有网络的环境同步一次再切到其他设备继续编辑。7. 扩展玩法Haptic部署完成之后还能做什么7.1 与自动化工具的联动当Haptic跑稳定之后我开始琢磨一个事能不能让我记录的笔记“活”起来而不仅仅是躺在数据库里当前个人知识管理领域有一个很火的玩法叫“知识库自动化”核心逻辑是把笔记当作输入源通过定时任务或事件触发的方式自动完成一些数据处理流程。举例来说我给自己搭了一条链路在Haptic里建了一篇“问题待处理”的笔记写了一个脚本每天定时抓取这篇笔记检查里面有没有新增的内容如果发现新增内容就通过邮件推送到我的邮箱并把笔记里的状态标记置为“已处理”。这些看似基础的操作放在以前商业笔记里做起来总是绕不开平台限制但在本地部署的自托管环境下整个流程完全由自己掌控。Haptic的数据以结构化方式存储随便写一段脚本就能读取。这个扩展思路对日常记录习惯比较重的用户来说非常实用。7.2 与其他自托管服务的组合做完了Haptic的部署之后我突然发现自己的服务器上已经跑了好几个自托管应用笔记管理、网盘、定时任务调度、代码仓库。它们之间如果能联动起来价值会叠加。举个例子我在网盘里存了一批技术文档的PDF然后写了一个脚本定期把它们转换并导入Haptic对应目录同时通过Haptic的API把文档的摘要和标签更新进去。这样我只需要在网盘里丢文件Haptic这边就自动多了一批整理好的笔记。这个工作流完全基于自托管生态不存在任何数据泄露出本机的风险。更进一步的玩法是接入自部署的OCR服务。经常收到一些扫描版PDF没办法直接复制文字我之前会手动转成图片再OCR现在直接把文件丢进一个监控目录自动OCR的文字结果导入Haptic笔记然后配上原文链接。这个过程如果放到线上服务里要么收费要么有文件大小限制本地部署之后完全不存在这个问题。如果你对这些玩法感兴趣我的建议是先从最简单的做起试着用脚本读取一篇Haptic笔记的内容然后写入另一个文件。跑通这一步你就具备了把Haptic和自己工作流串联的基础能力。个人来说搭建Haptic这套笔记环境表面上是在解决“笔记工具”的问题实际上是在构建一套完全属于自己的知识基础设施。数据在自己手里、入口在自己手里、扩展逻辑也完全在自己手里。如果后面要继续扩展我最想做的事情是给这套笔记环境加上自动标签功能通过关键词和一些简单的规则让新笔记进库之后自动完成分类。等这套机制稳定了再考虑跟其他工具打通数据流。路要一步一步走先把基础部署做扎实再谈上层应用。