Docker搭建linkding私人书签库

浏览器收藏夹里的链接越来越多，技术文档、项目教程和常用工具混在一起，时间久了很难找到。换一台电脑或换一个浏览器，还需要重新整理收藏内容。

linkding 是一款支持自托管的书签管理工具，可以部署在自己的服务器上，通过网页集中管理链接，使用标签分类，并导入、导出浏览器书签。

本文从 Docker 安装开始，介绍如何搭建 linkding 私人书签库，配置域名 HTTPS，完成收藏、搜索和备份。

1. linkding 是什么

linkding 是一个开源书签管理项目，主要用于保存和整理网页链接。

它支持添加标题、描述和标签，可以按关键词或标签查找书签，也能通过 HTML 文件迁移浏览器收藏。项目提供 Docker 部署方式，默认使用 SQLite 数据库。

项目官网：https://linkding.link

对于想集中整理技术资料、学习链接和常用网站的用户，linkding 的使用方式比较直接：保存网址，添加标签，需要时搜索。

2. 本次教程实现什么

完成部署后，可以使用自己的域名登录书签库，并实现以下功能：

• 保存网页链接，整理标题和描述。
• 给同一条书签添加多个标签。
• 按关键词或组合标签搜索。
• 导入浏览器导出的 HTML 书签文件。
• 导出书签，并生成应用数据备份。

本次采用以下组合：

管理员通过服务器终端创建。本教程涉及的登录、书签管理和导入导出流程，不需要配置邮件服务器。

3. 搭建环境

本次建议准备以下配置：

• CPU：建议 2 核及以上
• 内存：建议 2GB 及以上
• 磁盘：建议 20GB 及以上可用空间
• 系统：Debian 12 或 Ubuntu 24.04
• Docker：Docker Engine
• Compose：Docker Compose V2
• 域名：一个可以管理 DNS 解析的域名或子域名
• 对外端口：TCP 80 和 443
• 应用内部端口：9090

以上资源配置是本教程的小规模使用建议，并非项目官方最低要求。书签数量、预览资源和备份文件增加后，需要相应预留磁盘空间。

本次教程推荐使用莱卡云 Linux 云服务器进行搭建。建议使用新装系统，方便确认端口和运行环境。

查看官网购买链接： https://www.lcayun.com

9折优惠码：bloglcayun

域名准备

本文使用 links.example.com 作为示例，操作时必须替换为自己的真实域名。

在域名解析控制台添加一条 A 记录：

如果该子域名还配置了 AAAA 记录，需要确保 IPv6 同样指向这台服务器并且能够访问。没有部署 IPv6 时，应删除错误的 AAAA 记录。

在云服务器安全组中放行入站 TCP 80 和 443。如果系统启用了防火墙，也需要允许这两个端口，并保留实际使用的 SSH 端口。

本方案要求服务器的 80 和 443 端口空闲。如果已有网站或面板占用这两个端口，应先安排好端口和反向代理配置。

4. 安装 Docker 和 Compose

通过 SSH 登录服务器。以下命令均在服务器终端执行，以 root 用户操作；普通用户可以先执行：

sudo -i

下面的安装命令适用于新装 Debian 或 Ubuntu，使用 Docker 官方软件源，同时安装 Compose 插件和后续需要用到的 nano 编辑器。

bash <<'DOCKER'
set -e
. /etc/os-release

case "$ID" in
  debian|ubuntu) ;;
  *) echo '本段仅适用于 Debian 或 Ubuntu'; exit 1 ;;
esac

apt-get update
apt-get install -y ca-certificates curl nano

install -m 0755 -d /etc/apt/keyrings

curl -fsSL "https://download.docker.com/linux/$ID/gpg" \
  -o /etc/apt/keyrings/docker.asc

chmod a+r /etc/apt/keyrings/docker.asc

cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/$ID
Suites: ${UBUNTU_CODENAME:-$VERSION_CODENAME}
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt-get update

apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

systemctl enable --now docker

docker --version
docker compose version
docker run --rm hello-world
DOCKER

正常情况下，最后会显示 Docker、Compose 的版本，并输出 hello-world 的成功提示。

如果下载或安装出现报错，应先解决网络、软件源或安装问题，再继续后面的部署。

已经安装 Docker 和 Compose 的服务器，可以先执行以下命令检查，无需重复安装：

docker --version
docker compose version
docker run --rm hello-world

5. 创建 linkding 部署配置

5.1 创建项目目录

mkdir -p /opt/linkding
cd /opt/linkding

创建域名配置文件。先将下面的示例域名替换为真实域名，再执行：

printf 'DOMAIN=links.example.com\n' > .env

这里仅填写域名，不要包含 https://、端口或路径。

例如：

DOMAIN=links.example.com

5.2 创建 Compose 文件

执行：

nano compose.yaml

粘贴以下完整内容：

services:
  linkding:
    image: sissbruecker/linkding:1.47.0
    restart: unless-stopped
    environment:
      LD_CSRF_TRUSTED_ORIGINS: "https://${DOMAIN}"
    volumes:
      - ./data:/etc/linkding/data
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  caddy:
    image: caddy:2.11.9-alpine
    restart: unless-stopped
    depends_on:
      - linkding
    environment:
      DOMAIN: "${DOMAIN:?请先填写域名}"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy/data:/data
      - ./caddy/config:/config
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

按 Ctrl+O，回车保存，再按 Ctrl+X 退出。

其中：

• ./data 保存 linkding 数据，实际位置是 /opt/linkding/data。
• LD_CSRF_TRUSTED_ORIGINS 指定浏览器访问时使用的 HTTPS 地址。
• Caddy 使用 80 和 443 提供网页访问。
• ./caddy/data 保存证书等运行数据。
• 镜像采用固定版本，便于保持教程和录屏环境一致。

linkding 官方提供了反向代理相关配置项，访问域名应与配置的可信来源保持一致。

5.3 创建 Caddy 配置

执行：

nano Caddyfile

粘贴：

{$DOMAIN} {
    encode zstd gzip
    reverse_proxy linkding:9090
}

保存并退出。

{$DOMAIN} 会读取容器中的域名环境变量。域名解析和端口条件满足后，Caddy 会自动申请证书，并负责后续续期。

6. 启动服务并创建管理员

6.1 检查域名和端口

将命令中的域名替换为自己的域名：

getent ahostsv4 links.example.com

确认解析结果包含服务器公网 IPv4 地址。

检查端口占用：

ss -lntp '( sport = :80 or sport = :443 )'

如果已有程序监听这两个端口，需要先处理冲突。

6.2 启动容器

进入项目目录并检查配置：

cd /opt/linkding
docker compose config -q

没有报错后，再执行：

docker compose pull
docker compose up -d

查看运行状态和日志：

docker compose ps
docker compose logs --tail=80 linkding caddy

正常情况下，两个服务都会进入运行状态。

首次启动时，linkding 需要初始化数据库，Caddy 需要申请证书。容器显示 Up 后，还应确认实际网页能够打开。

6.3 创建管理员

在项目目录执行：

docker compose exec linkding python manage.py createsuperuser \
  --username admin --email demo@example.com

把 demo@example.com 换成自己的邮箱。

按照提示输入两次密码。输入时终端不显示字符属于正常现象。

看到以下提示，表示账户创建完成：

Superuser created successfully.

这里填写邮箱是创建账户资料，不需要先搭建邮件服务器。终端创建管理员是项目官方支持的方式。

7. 登录并使用私人书签库

在电脑浏览器中打开自己的域名：

https://links.example.com

确认浏览器没有证书警告，然后使用刚才创建的用户名和密码登录。

7.1 添加网页书签

点击 Add bookmark，填写需要收藏的网址。

检查网页标题和描述，再添加标签，点击 Save 保存。

如果目标网站不允许自动抓取标题，或者服务器暂时无法访问该网站，可以手动填写标题后保存。

可以先用本站以下三篇教程进行测试：

同一条书签可以添加多个标签。例如，Cloudreve 教程可以同时添加 docker 和 storage。

保存完成后，回到列表确认三条书签及对应标签均已显示。

作为私人书签库使用时，新增书签保持 Share 未勾选。在设置中保持 Internet Archive integration 关闭，避免启用向第三方归档服务提交网址的功能。

7.2 使用关键词和标签搜索

可以直接输入标题中的关键词查找书签。

按标签搜索时，在标签名称前加上 #。

例如：

#docker

查找同时包含两个标签的书签：

#docker #storage

按照前面的示例，第一条搜索应找到三篇 Docker 教程，第二条则只找到 Cloudreve 教程。多个标签组合可以缩小结果范围。

7.3 导入和导出浏览器书签

导入书签：

1. 在浏览器的书签管理页面，将收藏导出为 HTML 文件。
2. 打开 linkding 的 Settings → General。
3. 找到 Import，选择导出的 HTML 文件。
4. 保持 Import public bookmarks as shared 未勾选。
5. 点击导入，完成后返回列表检查结果。

第一次测试建议只导入少量公开链接，确认标题、标签和数量符合预期，再迁移完整收藏。

导出书签：

在 Settings → General 中找到 Export，点击 Download，下载 HTML 文件。

导出的 HTML 适合迁移自己的书签，但不会完整包含用户资料和应用资源，因此仍需要进行下一节的数据备份。

8. 数据备份与日常维护

8.1 生成完整应用备份

本教程使用默认 SQLite 数据库，可以调用 linkding 提供的完整备份命令。

在服务器执行：

cd /opt/linkding

backup_name="linkding-$(date +%Y%m%d-%H%M%S).zip"

docker compose exec -T linkding python manage.py full_backup \
  "/etc/linkding/data/$backup_name" &&
docker compose exec -T linkding python -m zipfile -t \
  "/etc/linkding/data/$backup_name" &&
ls -lh "./data/$backup_name"

命令会生成带时间的 ZIP 备份文件，检查压缩包，并显示文件大小。

由于数据目录已经挂载到宿主机，备份文件可以直接在以下目录找到：

/opt/linkding/data

使用 SFTP 等方式将备份下载到自己的电脑或其他备份位置。同时保存以下配置文件：

• /opt/linkding/.env
• /opt/linkding/compose.yaml
• /opt/linkding/Caddyfile

完整备份包含数据库及相关应用资源；配置文件需要另外保存。备份中可能包含账户和私人书签数据，应妥善保管。

8.2 检查数据是否持久保存

保存几条测试书签后，可以执行：

cd /opt/linkding
docker compose restart

等待服务恢复，再次登录，确认书签仍然存在。

日常维护时应保留 /opt/linkding/data，并定期把备份复制到服务器之外。

恢复备份时，建议先在独立测试目录使用相同镜像版本验证：将 ZIP 内容解压到新的 data 目录，确保其中直接包含 db.sqlite3，再挂载到容器的 /etc/linkding/data。确认用户和书签正常后，再安排正式迁移。

8.3 更新版本

更新前先完成备份，并阅读目标版本的更新说明。

修改 compose.yaml 中需要更新的镜像版本后，执行：

cd /opt/linkding
docker compose pull
docker compose up -d
docker compose ps

更新完成后，检查登录、添加书签和搜索功能。

如果修改了 .env 或 Compose 环境变量，也应执行 docker compose up -d，让配置应用到容器。

9. 常见问题

9.1 域名打不开，或者 HTTPS 证书申请失败

依次检查：

• A 记录是否指向正确的服务器公网 IP。
• 是否存在错误的 AAAA 记录。
• 安全组和防火墙是否允许 TCP 80、443。
• 这两个端口是否被其他程序占用。
• .env 中是否填写了真实域名。

查看 Caddy 日志：

cd /opt/linkding
docker compose logs --tail=100 caddy

9.2 页面出现 502

先查看 linkding 的状态和日志：

cd /opt/linkding
docker compose ps
docker compose logs --tail=100 linkding

首次启动时，可以等待应用初始化完成后再刷新。

如果一直无法恢复，需要根据日志检查容器是否退出、数据目录是否可写，以及配置文件是否存在拼写错误。

9.3 登录或保存时出现 CSRF 错误

检查浏览器地址是否与 .env 中的域名一致，并确认使用 HTTPS 访问。

修改域名配置后执行：

cd /opt/linkding
docker compose up -d

不要把可信来源配置成与实际访问地址不同的域名。反向代理后的来源地址不一致，是项目官方列出的相关排查方向。

9.4 忘记管理员密码怎么办

在服务器执行：

cd /opt/linkding
docker compose exec linkding python manage.py changepassword admin

按照提示设置新密码。如果管理员用户名不是 admin，替换成实际用户名。

9.5 收藏网页后，可以离线阅读完整内容吗

本教程使用普通版镜像，主要演示链接收藏和管理。

保存书签不等于完整保存网页。项目的自动网页 HTML 快照功能需要使用包含相应依赖的 plus 镜像，不能把普通版的收藏结果当成完整离线网页备份。

10. 结语

linkding 适合用来集中整理技术教程、工具网站和学习资料。通过标签分类和搜索，原本分散在浏览器收藏夹里的链接，可以形成一个方便查找的私人书签库。

完成本教程后，应确认域名 HTTPS、管理员登录、书签添加、标签搜索和导入导出均能正常使用，再逐步迁移自己的收藏内容。日常维护中，记得定期生成应用备份，并保存到服务器之外。

如果还希望监测书签库是否正常运行，可以继续参考本站的 Uptime Kuma 网站监控教程，为自己的服务添加可用性监控。