hugo/obsidian+couchdb 配置全过程

目录

vps+ hugo/obsidian+couchdb 配置全过程

在腾讯云购买了一台轻量级服务器VPS,(此时不需要 Fly.io,也不需要 Google Colab)。最初是为了配置CouchDB + obsidian全过程。后来在配置的过程中,因为想加反向代理,那么就折腾了一下域名的申请。

为什么要使用反向代理?

  1. HTTPS / SSL 证书(最刚需的理由)。IP + 端口无法安装受信任的公共 SSL 证书(除非购买昂贵的“IP 证书”,且极少 CA 机构签发)。即使安装了,浏览器也会报不安全。
  2. 端口封锁与穿透(国内网络环境痛点)。国内电信/联通宽带或云服务商安全组,默认会封禁 80、443 以外的绝大多数端口(或需要繁琐备案)。
  3. 多服务统一治理(路由能力)。一台 VPS 上通常跑着多个服务,如果用端口号容易记混。
  4. 安全隐蔽与攻击面收敛(防扫描)
  5. 运维灵活性(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自动登录

申请 SSL 证书 免费 SSL 证书申请流程_腾讯云

验证 SSL 证书 DNS 验证_腾讯云

三、第二步:先更新 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 安装方式配置软件源。

GitHub - caddyserver/caddy: Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS · GitHub

使用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>
    <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