🚀 使用 Docker Compose 部署 Linkwarden

Linkwarden 是一款开源的书签管理工具，专为需要高效收集、组织和检索网络资源的用户设计。它不仅可以保存网页链接，还能抓取网页快照，确保即使原始内容消失也能随时查阅。

📖 项目简介

Linkwarden 是一个自托管的书签管理解决方案，具有以下核心特性：

完整内容保存：不仅保存链接，还能抓取网页内容生成快照，防止链接失效
智能分类：强大的标签系统和搜索功能，轻松整理和查找收藏内容
团队协作：支持多用户协作，团队成员可以共享和管理书签集合
可视化展示：提供直观的内容预览，增强浏览和管理体验
数据自主：自托管方案确保你完全掌控自己的数据
现代化架构：基于 Next.js 开发，提供流畅的用户界面和体验

⚙️ 部署前准备

环境要求
- 已安装 Docker 和 Docker Compose
- 至少 2GB 可用内存（推荐 4GB 以上）
- 足够的磁盘空间存储网页快照和数据库
创建项目目录 建议创建一个独立目录来管理所有部署文件：

mkdir linkwarden && cd linkwarden

🔧 配置 Docker Compose

1.创建 docker-compose.yml 文件将你提供的配置保存为 docker-compose.yml：

#version: '3.8'
services:
  postgres:
    image: postgres:16-alpine  # PostgreSQL 16 轻量版本（体积小、启动快）  # 使用 Alpine 版本，体积更小
    env_file: .env   # 加载数据库密码等环境变量（从 .env 读取） # 统一通过 .env 文件管理环境变量
    restart: unless-stopped  # 容器退出后自动重启（数据库核心服务，需稳定）
    #5432/tcp 映射的端口
    volumes:
      #- postgres_data:/var/lib/postgresql/data  # 持久化数据库数据
      - ./postgres_data:/var/lib/postgresql/data  # 数据库数据持久化（删除会丢失所有链接数据）
    networks:
      - linkwarden_network  # 加入自定义网络，与 Linkwarden 通信
    deploy:
     resources:
       limits:  # 资源限制（避免数据库占用过多 CPU/内存）
        cpus: '5'   # 最多使用 5 个 CPU 核心
        memory: 1G   # 最多使用 1GB 内存


  linkwarden:
    image: ghcr.io/linkwarden/linkwarden:latest    # 官方最新镜像（自动更新稳定版）
    env_file: .env  # 加载应用环境变量
    environment:
      # 数据库连接地址：格式为 postgresql://用户名:密码@数据库容器名:端口/数据库名
      - DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/postgres
    depends_on:
      - postgres  # 依赖 PostgreSQL 服务（确保数据库先启动）
    ports:
      - "3100:3000"    # 端口映射：主机 3100 → 容器 3000（Web 界面访问端口）宿主机的 3000 端口映射到容器的 3000 端口
    volumes:
      #- linkwarden_data:/data/data  # 持久化应用数据（如上传的文件）
      #- ./linkwarden_data:/data/data  # 持久化应用数据（如上传的文件）
      # 应用数据持久化（保存上传文件、缓存等，删除不影响链接元数据）
      - /mnt/10t/cache/linkwarden_data:/data/data
    restart: unless-stopped  # 容器退出后自动重启
    networks:
      - linkwarden_network  # 加入自定义网络，与数据库通信
    deploy:
     resources:
       limits:  # 资源限制（根据服务器配置调整，避免卡顿）
        cpus: '9'    # 最多使用 9 个 CPU 核心
        memory: 5G   # 最多使用 5GB 内存


#volumes:
  #postgres_data:
  #linkwarden_data:

# 自定义网络：隔离 Linkwarden 相关服务，避免端口冲突
networks:
  linkwarden_network:
    driver: bridge

2.创建 .env 环境变量文件将你提供的环境变量保存为 .env 文件，并确保修改关键密码：

# 1. PostgreSQL 数据库密码（必须修改！建议用字母+数字+符号的强密码）
#POSTGRES_PASSWORD=your_secure_postgres_password_here
POSTGRES_PASSWORD=BaLt42Ncd7s3XX6  # 用户提供的默认密码，生产环境建议替换为更强密码


# 2. NextAuth.js 密钥（用于加密用户会话，必须随机！）
# NextAuth.js 的**重要**密钥，用于加密会话和令牌。请用长随机字符串。
# 生成命令：openssl rand -base64 32（替换下方默认值，避免安全风险）
#NEXTAUTH_SECRET=your_very_long_and_random_nextauth_secret_here
NEXTAUTH_SECRET=u6bTPDI1p0fSkbrfZ8wIRg+fsl8WEzvGVHGztlgr0Wc=

# 3. 应用访问 URL（关键！需与实际访问地址一致，否则登录失败）
# 若通过服务器IP访问：http://服务器IP:3100（如 http://192.168.1.100:3100）
# 若通过域名访问：https://你的域名（需配置反向代理）
NEXTAUTH_URL=http://localhost:3100  # 本地测试用，远程访问需改为服务器IP或域名

# 4. （可选）禁用注册（首次创建管理员账号后建议设为 true，防止他人注册）
# NEXT_PUBLIC_DISABLE_REGISTRATION=false

关键配置说明：

服务依赖：Linkwarden 服务通过 depends_on 确保在 PostgreSQL 数据库之后启动
网络配置：自定义的 linkwarden_network 允许两个服务在隔离的网络中通信
数据持久化：
./postgres_data：保存 PostgreSQL 数据库文件
/mnt/10t/cache/linkwarden_data：保存 Linkwarden 的应用数据和网页快照
资源限制：为两个服务分别设置了 CPU 和内存使用上限

配置项关键说明2（新手必看）

配置项	作用与注意事项
`DATABASE_URL`	数据库连接核心配置，格式为 `postgresql://用户名:密码@容器名:端口/数据库名`，`postgres` 容器名不可随意修改（与服务名一致）。
`POSTGRES_PASSWORD`	数据库密码是核心安全项，默认值 `BsLt42Ncd7s3XX6` 风险高，生产环境必须替换为强密码（如 `LinkwardenDB@2024!`）。
`NEXTAUTH_SECRET`	缺失或过简单会导致用户登录异常，务必用 `openssl rand -base64 32` 生成随机字符串。
`NEXTAUTH_URL`	必须与实际访问地址一致（如远程访问用 `http://192.168.1.100:3100`），否则登录时会提示 “回调地址不匹配”。
目录挂载	`./postgres_data` 和 `/mnt/10t/.../linkwarden_data` 不可随意删除，否则会丢失数据库和应用数据。

🚀 启动与验证

启动服务 在项目目录下执行： bash docker compose up -d 首次运行会拉取镜像并启动容器。
验证部署
- 检查容器状态： bash docker compose ps 确认两个容器状态均为 Up
- 查看启动日志： bash docker compose logs -f linkwarden
- 访问应用：打开浏览器访问 http://你的服务器IP:3100

🛠️ 基础配置与使用

初始账户设置
- 首次访问会显示注册页面
- 创建管理员账户（建议完成后在环境变量中设置 NEXT_PUBLIC_DISABLE_REGISTRATION=true 禁用公开注册）
基础配置
- 时区设置：确保服务器时区正确，以保证书签时间戳准确
- 存储路径验证：确认挂载的卷有足够空间保存网页快照
- 备份策略：定期备份 PostgreSQL 数据和 Linkwarden 上传的文件
日常使用
- 浏览器书签导入：支持从主流浏览器导入现有书签
- 浏览器扩展：可安装官方浏览器扩展，一键保存网页到 Linkwarden
- API 访问：Linkwarden 提供 REST API，支持与其他工具集成

🛠️ 基础配置与使用2

登录后，新手需完成 “禁用注册”“添加书签”“分类管理” 等核心操作，确保工具安全可用：

1. 步骤 1：禁用公开注册（安全必备）

首次创建管理员账号后，建议禁用注册功能，防止未授权用户登录：

编辑 .env 文件，取消 NEXT_PUBLIC_DISABLE_REGISTRATION 的注释并设为 true：

NEXT_PUBLIC_DISABLE_REGISTRATION=true

重启 Linkwarden 容器使配置生效：

docker compose restart linkwarden

再次访问 http://服务器IP:3100，注册入口会消失，仅支持已有账号登录。

2. 步骤 2：添加第一个书签

主界面点击右上角「Add a New Link」→ 选择「Link」（添加网页链接）；
填写关键信息：
- URL：输入网页链接（如 https://docs.docker.com）；
- Title：自定义书签标题（如 “Docker 官方文档”）；
- Description：添加备注（如 “Docker 安装与使用指南”）；
- Tags：添加标签（如 “技术文档”“Docker”，多个标签用逗号分隔）；
- Collection：选择或创建集合（如 “开发资源”，类似文件夹分类）；
点击「Save」，书签会显示在对应集合中，支持点击链接直接跳转。

3. 步骤 3：管理与检索书签

分类查看：左侧菜单栏点击「Collections」，选择对应集合（如 “开发资源”），查看该分类下的所有书签；
搜索书签：顶部搜索框输入关键词（如 “Docker”），会实时筛选含该关键词的书签（标题、描述、标签均会匹配）；
编辑 / 删除：书签卡片右侧点击「⋮」→ 选择「Edit」修改信息或「Delete」删除书签。

4. 步骤 4：导出书签（数据备份）

为防止数据丢失，可定期导出书签为 JSON 文件：

点击右上角头像 →「Settings」→「Export Data」；
点击「Export」，浏览器会自动下载 linkwarden-export.json 文件（包含所有书签信息）。

🔄 维护与管理

服务管理
- 停止服务：docker compose down
- 重启服务：docker compose restart
- 更新服务： bash docker compose pull docker compose up -d
数据备份
- 数据库备份： bash docker compose exec postgres pg_dump -U postgres postgres > backup.sql
- 完整备份：定期备份 postgres_data 和 linkwarden_data 目录
日志查看
- 查看实时日志：docker compose logs -f linkwarden
- 查看特定服务日志：docker compose logs postgres

❓ 常见问题排查

容器启动失败
- 检查端口冲突：确保宿主的 3100 端口未被占用
- 验证环境变量：确保 .env 文件中所有变量已正确设置
- 查看详细日志：使用 docker compose logs linkwarden 查看具体错误信息
无法访问 Web 界面
- 检查防火墙：确保服务器防火墙允许 3100 端口访问
- 验证服务状态：确认所有容器正常运行：docker compose ps
数据库连接错误
- 检查依赖启动顺序：确保 PostgreSQL 容器在 Linkwarden 之前完全启动
- 验证密码：确保 .env 中的 POSTGRES_PASSWORD 与 DATABASE_URL 中的密码一致
性能问题
- 资源监控：使用 docker stats 查看容器资源使用情况
- 调整资源限制：根据实际使用情况调整 deploy.resources.limits 配置
容器崩溃与恢复
- 如果容器意外退出，可以检查其退出码。例如，退出码 137 通常表示容器因内存不足（OOM）被系统终止。
- 检查系统日志（如使用 dmesg -T 命令）以确认是否有 OOM 事件。
- 根据诊断情况，可以考虑适当调整 deploy 部分中的内存限制。

通过以上步骤，你应该能够成功部署并运维自己的 Linkwarden 实例。如果在使用过程中遇到特定问题，可以查阅 Linkwarden 官方文档或社区论坛获取更多支持。