hugo/obsidian+couchdb 配置全过程
目录
vps+ hugo/obsidian+couchdb 配置全过程
在腾讯云购买了一台轻量级服务器VPS,(此时不需要 Fly.io,也不需要 Google Colab)。最初是为了配置CouchDB + obsidian全过程。后来在配置的过程中,因为想加反向代理,那么就折腾了一下域名的申请。
为什么要使用反向代理?
- HTTPS / SSL 证书(最刚需的理由)。IP + 端口无法安装受信任的公共 SSL 证书(除非购买昂贵的“IP 证书”,且极少 CA 机构签发)。即使安装了,浏览器也会报不安全。
- 端口封锁与穿透(国内网络环境痛点)。国内电信/联通宽带或云服务商安全组,默认会封禁 80、443 以外的绝大多数端口(或需要繁琐备案)。
- 多服务统一治理(路由能力)。一台 VPS 上通常跑着多个服务,如果用端口号容易记混。
- 安全隐蔽与攻击面收敛(防扫描)
- 运维灵活性(IP 变更无感知)
采用的架构为
Ubuntu → Docker → CouchDB → Caddy HTTPS → Obsidian LiveSync
其中 CouchDB 作为单节点数据库即可。Apache CouchDB 官方本身就明确支持单节点部署,而且 CouchDB 使用 HTTP/JSON API,很适合通过反向代理提供服务。(Apache CouchDB)
下面按照"从刚买好的 VPS 开始,到 Windows Obsidian 成功同步"的顺序进行。
一、最终架构
我们最终搭成:
Internet
│
HTTPS :443
│
▼
┌───────────────┐
│ Caddy │
│ HTTPS反向代理 │
└───────┬───────┘
│
HTTP :5984
│
▼
┌───────────────┐
│ CouchDB │
│ Docker容器 │
└───────┬───────┘
│
Docker Volume
│
▼
/opt/couchdb/data
│
▼
你的 LiveSync 数据
然后客户端:
Windows Obsidian
│
│ LiveSync
▼
HTTPS
│
▼
Caddy
│
▼
CouchDB
Android、另一台电脑也是完全相同的路径。
这里有一个重要的安全设计:
公网只开放 443,不直接开放 CouchDB 的 5984。
CouchDB 默认 HTTP 服务使用 5984,而官方文档也支持通过反向代理把外部 HTTPS 请求转发到本机 CouchDB。(CouchDB Documentation)
二、第一步:登录腾讯云服务器(确保ICP和公安备案,安装了ssl证书)
你在腾讯云控制台找到刚购买的轻量服务器。
首先确认:
公网 IPv4:xxx.xxx.xxx.xxx
操作系统:Ubuntu 24.04 LTS
Windows 11 自带 OpenSSH,一般直接打开 PowerShell:
ssh root@你的公网IP
例如:
ssh root@123.123.123.123
第一次连接会出现:
Are you sure you want to continue connecting?
输入:
yes
然后输入腾讯云设置的 root 密码。
成功后应该看到类似:
root@VM-xxxx:~#
现在你已经进入 VPS。
可以设置ssh自动登录
三、第二步:先更新 Ubuntu
执行:
apt update
apt upgrade -y
然后安装几个基础工具:
apt install -y curl wget vim nano ufw ca-certificates
确认系统:
lsb_release -a
应该看到:
Ubuntu 24.04 LTS
四、第三步:确认你的 Docker
你购买的是:
Ubuntu24.04-Docker29
所以大概率已经安装 Docker 29。
执行:
docker --version
再执行:
docker compose version
如果看到类似:
Docker version 29.x.x
Docker Compose version v2.x.x
就不需要重新安装 Docker。
Docker 官方目前也建议使用 Docker Engine 和 Docker Compose 管理容器化应用。(Docker Documentation)
再检查:
systemctl status docker
如果显示:
Active: active (running)
说明 Docker 正常。
五、第四步:创建 CouchDB 工作目录
不要把配置文件随便扔在 /root。
建立:
mkdir -p /opt/couchdb
cd /opt/couchdb
然后建立数据目录:
mkdir -p data
最终:
/opt/couchdb/
├── data/
└── ...
这个 data 非常重要。
因为:
CouchDB 数据最终就保存在这里对应的 Docker 持久化存储中。
所以以后即使删除 CouchDB 容器,只要这个数据卷还在,数据库数据就不会因为"容器删除"而消失。
六、第五步:创建 CouchDB Docker Compose
创建:
nano /opt/couchdb/compose.yml
写入:
services:
couchdb:
image: couchdb:3
container_name: couchdb
restart: unless-stopped
environment:
COUCHDB_USER: admin
COUCHDB_PASSWORD: 请修改成你的强密码
volumes:
- couchdb-data:/opt/couchdb/data
ports:
- "127.0.0.1:5984:5984"
volumes:
couchdb-data:
这里有一个非常关键的地方:
ports:
- "127.0.0.1:5984:5984"
而不是:
- "5984:5984"
前者意味着:
公网
X
│
5984
│
CouchDB
公网无法直接访问 CouchDB。
只有 VPS 本机能够访问:
127.0.0.1:5984
然后以后让:
HTTPS :443
↓
Caddy
↓
127.0.0.1:5984
↓
CouchDB
这样安全性明显更好。
七、为什么要使用管理员账号?
上面的:
COUCHDB_USER: admin
COUCHDB_PASSWORD: ...
会创建 CouchDB 管理员。
例如:
Username:
admin
Password:
你的强密码
这个账号用于管理 CouchDB。
不要使用:
admin / 123456
建议使用随机高强度密码,例如至少 20 位。
而且这个密码以后不要发给我,也不要放到公开 GitHub 仓库。
八、启动 CouchDB
进入目录:
cd /opt/couchdb
然后:
docker compose up -d
检查:
docker ps
应该看到:
couchdb
状态类似:
Up
然后查看日志:
docker logs couchdb
如果没有持续出现 error,基本正常。
九、测试 CouchDB
在 VPS 内执行:
curl http://127.0.0.1:5984/
正常情况下应该返回 JSON,例如:
{
"couchdb": "Welcome",
"version": "3.x.x"
}
然后测试管理员认证:
curl -u admin:'你的密码' http://127.0.0.1:5984/_all_dbs
如果返回:
[]
就很好。
这意味着:
CouchDB 已经正常运行。
/_all_dbs 是 CouchDB 官方 HTTP API 的数据库列表接口。(CouchDB Documentation)
十、这里先不要急着配置 Obsidian
现在你只是完成:
Ubuntu
↓
Docker
↓
CouchDB
还差:
HTTPS
域名
CORS
LiveSync
其中HTTPS 是必须认真处理的部分。
不要把:
http://你的公网IP:5984
直接填写到 LiveSync,然后长期裸奔。
十一、准备一个域名
建议准备一个域名,例如:
couch.example.com
最终:
https://couch.example.com
指向你的腾讯云公网 IP。
在 DNS 服务商处添加:
类型:A
主机记录:couch
记录值:你的腾讯云公网IP
例如:
couch.example.com
↓
123.123.123.123
然后在 VPS 上测试:
ping couch.example.com
注意这里部署了couch就通不了。
或者:
getent hosts couch.example.com
如果能解析到你的公网 IP,就可以继续。
十二、腾讯云安全组
现在进入腾讯云轻量服务器的防火墙/安全组。
我们最终只需要:
22 SSH
80 HTTP
443 HTTPS

建议:
SSH 22
TCP 80
TCP 443
而:
5984
不要开放公网访问。
也就是说:
Internet
│
├── 22 SSH
├── 80 HTTP → Caddy
└── 443 HTTPS → Caddy
不要:
Internet → 5984 → CouchDB
十三、配置 Ubuntu 防火墙
在 VPS 中:
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
然后:
ufw enable
确认:
ufw status
应该看到:
22/tcp
80/tcp
443/tcp

十四、安装 Caddy
我们使用 Caddy 做 HTTPS 反向代理。
原因是它非常适合这种:
Internet
↓
HTTPS
↓
Caddy
↓
CouchDB
而且 Caddy 可以自动申请和续期 TLS 证书。
安装:
apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
然后按照 Caddy 官方 Ubuntu/Debian 安装方式配置软件源。
使用apt安装

安装完成:
caddy version
确认:
v2.x.x
十五、配置 Caddy
编辑:
nano /etc/caddy/Caddyfile
写:
couch.example.com {
reverse_proxy 127.0.0.1:5984
}
把:
couch.example.com
换成你的真实域名。
然后:
systemctl reload caddy
如果 Caddy 尚未运行:
systemctl enable --now caddy
查看:
systemctl status caddy
十六、测试 HTTPS
浏览器访问:
https://couch.example.com
如果正常,会看到 CouchDB 的:
Welcome
或者 JSON。我看到的json
这时候整个链路已经变成:
浏览器
↓
https://couch.example.com
↓
Caddy :443
↓
127.0.0.1:5984
↓
CouchDB
这一步非常关键。
只有这里成功以后,才开始配置 Obsidian。
hugo博客
整体架构
假设你的域名是:
example.com
我建议直接规划成:
example.com → 个人博客
sync.example.com → CouchDB / Obsidian LiveSync
以后可以继续扩展:
rss.example.com → FreshRSS
git.example.com → Forgejo
status.example.com → Uptime Kuma
服务器内部:
Internet
│
│ 80 / 443
↓
Caddy
│
├── example.com
│ ↓
│ Blog
│
└── sync.example.com
↓
CouchDB
**博客和 CouchDB 不要共用一个域名路径。**尤其不要做成:
example.com/couchdb
而应该使用:
example.com
sync.example.com
这样后续维护、HTTPS、访问控制和故障隔离都更清晰。
确认域名 DNS
首先到你的域名 DNS 管理处添加:
类型 主机记录 值
A @ 你的服务器IPv4
A sync 你的服务器IPv4
如果你暂时没有 IPv6,就不要添加 AAAA。
最终:
example.com
↓
服务器 IPv4
sync.example.com
↓
服务器 IPv4
在服务器上检查:
dig +short example.com
dig +short sync.example.com
或者:
nslookup example.com
nslookup sync.example.com
应该都返回你的服务器公网 IP。
Caddy 获取公网 TLS 证书之前,DNS 和公网 80/443 连通性必须正确。(Caddy Web Server)
先安装 Hugo
这里有两种开发方式。
我更推荐你:
Windows/Mac 本地写博客 → Git → 服务器部署
不要直接 SSH 到服务器上写文章。
你的电脑负责:
VS Code
Obsidian
Hugo
Git
服务器负责:
Caddy
静态文件
CouchDB
Hugo 官方目前要求 Hugo 和 Git,并使用 hugo new project 创建项目。(Hugo)
你 Windows 上可以先检查:
hugo version
git --version
如果还没有 Hugo,可以使用官方推荐的安装方式。
你的 Mac 也安装一份 Hugo,这样三个平台都能写博客。
安装hugo
安装 Hugo - KOK博客 使用winget安装,只需要在Windows上安装。
创建自己的博客
hugo new site Blog
Congratulations! Your new Hugo project was created in E:\A_LifeOS\Blog.
Just a few more steps...
1. Change the current directory to E:\A_LifeOS\Blog.
2. Create or install a theme:
- Create a new theme with the command "hugo new theme <THEMENAME>"
- Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>\<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".
See documentation at https://gohugo.io/.
设置主题 Title Unavailable | Site Unreachable

第四步:创建博客
例如你的博客源码放:
E:\A_LifeOS\Blog
执行:
cd E:\A_LifeOS
hugo new site Blog
cd Blog
git init
此时:
Blog/
├── archetypes/
├── assets/
├── content/
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
├── hugo.toml
└── ...
Hugo 最终会把网站生成到:
public/
例如:
Blog/
├── content/
│ ├── posts/
│ └── about/
│
├── static/
├── layouts/
├── themes/
├── hugo.toml
└── public/
第五步:选择主题
这里我建议你不要一开始就自己从零写主题。
你比较适合选择一个:
- 极简
- Markdown 友好
- 数学公式支持良好
- 代码高亮
- 暗色模式
- 移动端适配
- 不依赖大量 JavaScript
的 Hugo 主题。
尤其你以后很可能写:
电力系统分析
电力电子
继电保护
C语言
Linux
Windows
Obsidian
开源软件
所以博客最好是技术文档型,而不是图片博客或者营销型博客。
第一版建议先用一个成熟主题跑起来,不要花一个星期调 CSS。
例如可以先使用 Hugo 官方 Quick Start 中的 Ananke 作为验证环境;正式博客再换成自己选择的主题。(Hugo)
第六步:创建第一篇文章
例如:
hugo new content posts/hello-world.md
生成:
---
title: "Hello World"
date: 2026-08-31
draft: true
---
这是我的第一篇博客。
然后启动本地服务器:
hugo server -D
浏览器访问:
http://localhost:1313
看到博客以后,说明:
Hugo
↓
Markdown
↓
HTML
这一套已经跑通。
第七步:配置域名
编辑:
hugo.toml
例如:
baseURL = 'https://example.com/'
locale = 'zh-cn'
title = '你的博客名称'
theme = 'ananke'
如果博客主要使用中文:
locale = 'zh-cn'
如果以后需要中英文,可以再配置多语言,不需要现在增加复杂度。
第八步:生成生产版本
本地执行:
hugo
然后:
public/
就是最终网站。
例如:
public/
├── index.html
├── posts/
├── about/
├── categories/
├── tags/
├── css/
├── js/
└── images/
这一步非常重要:
服务器实际上不需要安装 Hugo。
服务器只需要 Caddy。
因为 Hugo 是:
$$ Markdown + Theme + Configuration \rightarrow Static HTML $$
服务器只负责:
$$ HTTP/HTTPS \rightarrow Static Files $$
这也是 Hugo 很适合你的轻量 VPS 的原因。
第九步:服务器创建博客目录
服务器上:
sudo mkdir -p /srv/blog
例如:
/srv/blog/
最终:
/srv/blog/
├── index.html
├── posts/
├── css/
├── js/
└── ...
把本地 public/ 上传:
rsync -avz --delete ./public/ user@server:/srv/blog/
Windows 可以使用:
scp -r .\public\* user@server:/srv/blog/
不过长期来看,我更建议 Git 自动部署,而不是每次手动 scp。
安装caddy
第十二步:访问博客
现在直接:
https://example.com
应该就能访问。
检查:
curl -I https://example.com
正常应该看到:
HTTP/2 200
或者:
HTTP/3 200
同时浏览器地址栏应该出现正常的 HTTPS 锁。
第十三步:现在就预留公安备案 Footer
你现在公安联网备案还在审核,因此不要填写假的公安备案编号。
但是博客主题现在就可以预留:
<footer>
<div>
© 2026 Your Name
</div>
<div>
ICP备案号
</div>
<div id="police-record">
<!-- 公安备案通过后,在这里放官方代码 -->
</div>
</footer>
等公安联网备案通过以后,把公安机关提供的官方备案标识代码放进去。
这样你的博客结构一开始就符合后续要求,不需要以后重新设计 Footer。
第十四步:把博客纳入 Git
这个对你非常重要。
十七、最终服务器架构
等第一阶段完成后,你的服务器可以形成:
Internet
│
80 / 443
│
Caddy
│
┌────────────┴────────────┐
│ │
example.com sync.example.com
│ │
Hugo Blog CouchDB
│ │
/srv/blog Obsidian LiveSync
然后第二阶段:
Caddy
│
┌──────────────┼──────────────┐
│ │ │
Blog CouchDB FreshRSS
│ │ │
example.com sync.example.com rss.example.com
第三阶段再考虑:
git.example.com
status.example.com
这样服务器就形成一个比较完整的个人互联网基础设施节点。
我建议你现在不要一次搭完所有东西
按照下面的顺序做最稳妥:
① DNS
↓
② Hugo 本地博客
↓
③ Git 管理
↓
④ 服务器 /srv/blog
↓
⑤ Caddy
↓
⑥ HTTPS
↓
⑦ example.com 正常访问
↓
⑧ 公安备案 Footer 预留
↓
⑨ sync.example.com
↓
⑩ CouchDB + Obsidian LiveSync
**先把博客跑起来,再接 CouchDB。**这样出现问题时容易定位:DNS、Caddy、博客静态文件、CouchDB、LiveSync 各自都是独立层。
如果你的服务器目前是你之前使用的 2 核 / 2 GB / 50 GB Linux 轻量服务器,并且已经安装 Docker/Podman,下一步可以直接按照这个架构给你写出一套可以复制执行的 /srv 目录结构 + docker-compose.yml + Caddyfile + Hugo 博客目录,然后再把 sync.example.com → CouchDB:5984 接进去。
使用hogo
学习教程 快速入门 | Hugo官方文档
hugo new content posts/hello-world.md
hugo server -D
http://localhost:1313
hugo
scp -r .\public\* xxx@xxx:xxx