Linkwarden 书签管理器部署流程

Linkwarden 书签管理器部署流程

系统要求

· 操作系统: Debian 12 (或其他 Linux 发行版)
· 内存: 最低 2GB，推荐 4GB+
· 存储: 至少 10GB 可用空间
· 网络: 可访问 Docker Hub 或配置镜像加速器

部署方法一：Docker 部署（推荐）

1. 系统准备

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装必要工具
sudo apt install -y curl nano

2. 安装 Docker

# 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

# 将用户添加到 docker 组
sudo usermod -aG docker $USER
newgrp docker

3. 配置 Docker 镜像加速器（国内服务器）

# 创建配置目录
sudo mkdir -p /etc/docker

# 配置镜像加速器
sudo tee /etc/docker/daemon.json << EOF
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}
EOF

# 重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

4. 部署 Linkwarden

# 创建项目目录
mkdir linkwarden && cd linkwarden

# 下载配置文件
curl -O https://raw.githubusercontent.com/linkwarden/linkwarden/refs/heads/main/docker-compose.yml
curl -L https://raw.githubusercontent.com/linkwarden/linkwarden/refs/heads/main/.env.sample -o ".env"

# 生成并配置环境变量
NEXTAUTH_SECRET=$(openssl rand -base64 32)
MEILI_MASTER_KEY=$(openssl rand -base64 32)
POSTGRES_PASSWORD=$(openssl rand -base64 32)

cat > .env << EOF
NEXTAUTH_URL=http://localhost:3000/api/v1/auth
NEXTAUTH_SECRET=$NEXTAUTH_SECRET
MEILI_MASTER_KEY=$MEILI_MASTER_KEY
POSTGRES_PASSWORD=$POSTGRES_PASSWORD
EOF

# 启动服务
docker-compose up -d

5. 验证部署

# 检查容器状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 检查端口监听
netstat -tulpn | grep :3000

6. 防火墙配置

# 开放 3000 端口
sudo ufw allow 3000
sudo ufw status

部署方法二：手动安装（适用于资源有限环境）

1. 安装依赖

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# 安装 PostgreSQL
sudo apt install -y postgresql postgresql-contrib

# 安装 Yarn
sudo npm install -g yarn

# 安装构建工具
sudo apt install -y git build-essential python3 make g++

2. 配置数据库

# 启动 PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# 创建数据库和用户
sudo -u postgres psql -c "CREATE USER linkwarden WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "CREATE DATABASE linkwarden WITH OWNER linkwarden;"

3. 部署应用

# 克隆代码
git clone https://github.com/linkwarden/linkwarden.git
cd linkwarden

# 安装依赖
yarn install

# 配置环境变量
cd linkwarden
cp .env.sample .env

# 编辑环境变量
nano .env

在 .env 文件中设置：

NEXTAUTH_SECRET=your_random_secret
NEXTAUTH_URL=http://localhost:3000/api/v1/auth
DATABASE_URL=postgresql://linkwarden:your_password@localhost:5432/linkwarden

4. 构建和启动

# 生成 Prisma 客户端
yarn prisma:generate

# 构建应用
yarn web:build

# 部署数据库
yarn prisma:deploy

# 启动应用
yarn concurrently:start

配置系统服务（生产环境）

创建 Systemd 服务

sudo nano /etc/systemd/system/linkwarden.service

添加以下内容：

[Unit]
Description=Linkwarden Bookmark Manager
After=network.target postgresql.service

[Service]
Type=simple
User=root
WorkingDirectory=/path/to/linkwarden/linkwarden
ExecStart=/usr/bin/yarn concurrently:start
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload
sudo systemctl enable linkwarden
sudo systemctl start linkwarden

访问和初始化

1. 访问应用: 打开浏览器访问 http://服务器IP:3000
2. 注册账户: 首次访问点击"注册"创建管理员账户
3. 开始使用: 登录后即可开始添加和管理书签

维护命令

Docker 方式

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 更新到最新版本
docker-compose pull
docker-compose up -d

# 查看日志
docker-compose logs -f

# 备份数据
tar czf linkwarden_backup_$(date +%Y%m%d).tar.gz pgdata/ data/ meili_data/

手动安装方式

# 重启服务
sudo systemctl restart linkwarden

# 查看日志
sudo journalctl -u linkwarden -f

# 更新应用
cd /path/to/linkwarden
git pull
yarn install
yarn prisma:generate
yarn web:build
sudo systemctl restart linkwarden

故障排除

常见问题

1. 内存不足: 创建交换空间 sudo fallocate -l 2G /swapfile
2. 端口占用: 修改 docker-compose.yml 中的端口映射
3. 数据库连接失败: 检查 .env 文件中的数据库连接字符串
4. 构建失败: 确保安装了所有构建依赖

日志查看

# Docker 方式
docker-compose logs [服务名]

# 手动安装方式
sudo journalctl -u linkwarden -f

安全建议

1. 使用强密码和随机密钥
2. 配置 HTTPS 和域名
3. 定期备份数据
4. 保持系统和应用更新
5. 使用防火墙限制访问

这个部署流程涵盖了从环境准备到生产部署的全过程，您可以根据实际需求选择合适的部署方式。