wallabag Docker镜像文档

1. 镜像概述和主要用途

wallabag 是一款自托管的网页保存应用，旨在帮助用户保存网页内容以便稍后阅读。与第三方服务不同，wallabag 完全开源免费，用户可自主掌控数据存储，避免依赖外部平台。通过该应用，用户可轻松保存网页、离线阅读，并有效管理个人知识库。

2. 核心功能和特性

• 自托管部署：支持在个人服务器部署，数据完全自主控制，保障隐私安全
• 开源免费：遵循开源协议，代码透明可审计，无功能限制
• 多数据库兼容：支持 SQLite（简易部署）、MariaDB/MySQL、PostgreSQL（生产环境推荐）
• 数据持久化：支持卷挂载，确保容器重启后数据不丢失
• 性能优化：可集成 Redis 实现缓存和异步任务处理
• 扩展功能：支持邮件通知、双因素认证、多平台数据导入（Pocket、Readability 等）
• 多语言支持：内置多种界面语言，可通过环境变量配置

3. 使用场景和适用范围

• 个人用户：保存网页文章、教程、博客等内容，实现离线阅读和知识整理
• 研究/教育场景：学者、学生收集网络资源，构建个人学***资料库
• 团队协作：共享阅读材料，协作整理行业资讯或项目文档
• 隐私敏感场景：不希望数据存储在第三方平台，需自建数据中心的用户

4. 使用方法和配置说明

4.1 默认登录凭据

初始登录用户名：wallabag，密码：wallabag

4.2 环境变量配置

4.3 数据库配置

4.3.1 SQLite（简易部署）

SQLite 无需额外数据库容器，适合测试或个人轻量使用：

# 临时运行（数据非持久化）
docker run -p 80:80 -e "SYMFONY__ENV__DOMAIN_NAME=http://localhost" wallabag/wallabag

访问 http://localhost 即可使用。为实现数据持久化，需挂载卷：

# 持久化运行（数据保存在宿主机 `/opt/wallabag`）
docker run -v /opt/wallabag/data:/var/www/wallabag/data \
  -v /opt/wallabag/images:/var/www/wallabag/web/assets/images \
  -p 80:80 \
  -e "SYMFONY__ENV__DOMAIN_NAME=http://localhost" \
  wallabag/wallabag

4.3.2 MariaDB / MySQL（生产环境推荐）

需先启动 MariaDB/MySQL 容器，再配置 wallabag 连接：

# 启动 MariaDB 容器（数据持久化到宿主机 `/opt/wallabag/db`）
docker run --name wallabag-db \
  -e "MYSQL_ROOT_PASSWORD=my-secret-pw" \
  -v /opt/wallabag/db:/var/lib/mysql \
  -d mariadb

# 启动 wallabag 并连接数据库
docker run --name wallabag \
  --link wallabag-db:wallabag-db \
  -e "MYSQL_ROOT_PASSWORD=my-secret-pw" \
  -e "SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql" \
  -e "SYMFONY__ENV__DATABASE_HOST=wallabag-db" \
  -e "SYMFONY__ENV__DATABASE_PORT=3306" \
  -e "SYMFONY__ENV__DATABASE_NAME=wallabag" \
  -e "SYMFONY__ENV__DATABASE_USER=wallabag" \
  -e "SYMFONY__ENV__DATABASE_PASSWORD=wallapass" \
  -e "SYMFONY__ENV__DATABASE_CHARSET=utf8mb4" \
  -e "SYMFONY__ENV__DOMAIN_NAME=http://localhost" \
  -p 80:80 \
  wallabag/wallabag

4.3.3 PostgreSQL

类似 MySQL，先启动 PostgreSQL 容器：

# 启动 PostgreSQL 容器
docker run --name wallabag-db \
  -e "POSTGRES_PASSWORD=my-secret-pw" \
  -e "POSTGRES_USER=my-super-user" \
  -v /opt/wallabag/db:/var/lib/postgresql/data \
  -d postgres:9.6

# 启动 wallabag 并连接数据库
docker run --name wallabag \
  --link wallabag-db:wallabag-db \
  -e "POSTGRES_PASSWORD=my-secret-pw" \
  -e "POSTGRES_USER=my-super-user" \
  -e "SYMFONY__ENV__DATABASE_DRIVER=pdo_pgsql" \
  -e "SYMFONY__ENV__DATABASE_HOST=wallabag-db" \
  -e "SYMFONY__ENV__DATABASE_PORT=5432" \
  -e "SYMFONY__ENV__DATABASE_NAME=wallabag" \
  -e "SYMFONY__ENV__DATABASE_USER=wallabag" \
  -e "SYMFONY__ENV__DATABASE_PASSWORD=wallapass" \
  -e "SYMFONY__ENV__DOMAIN_NAME=http://localhost" \
  -p 80:80 \
  wallabag/wallabag

4.4 Redis 集成（提升性能）

Redis 用于缓存和异步任务处理（如批量导入数据），支持两种集成方式：

4.4.1 Docker Link 方式

# 启动 Redis 容器
docker run -p 6379:6379 --name redis redis:alpine

# 启动 wallabag 并链接 Redis
docker run -p 80:80 \
  -e "SYMFONY__ENV__DOMAIN_NAME=http://localhost" \
  --link redis:redis \
  wallabag/wallabag

4.4.2 外部 Redis 主机

连接外部 Redis 服务器时，需指定主机和密码：

docker run -p 80:80 \
  -e "SYMFONY__ENV__REDIS_HOST=my.redis-server.com" \
  -e "SYMFONY__ENV__REDIS_PASSWORD=redis-pass" \
  -e "SYMFONY__ENV__DOMAIN_NAME=http://localhost" \
  wallabag/wallabag

4.5 升级方法

版本升级时需执行数据库迁移，确保数据结构兼容：

方法 1：运行 migrate 命令

docker run --link wallabag-db:wallabag-db \
  -e "MYSQL_ROOT_PASSWORD=my-secret-pw" \
  -e "SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql" \
  -e "SYMFONY__ENV__DATABASE_HOST=wallabag-db" \
  -e "SYMFONY__ENV__DATABASE_NAME=wallabag" \
  -e "SYMFONY__ENV__DATABASE_USER=wallabag" \
  -e "SYMFONY__ENV__DATABASE_PASSWORD=wallapass" \
  wallabag/wallabag migrate

方法 2：容器内手动执行迁移

# 替换 <container_id> 为 wallabag 容器 ID 或名称
docker exec -t <container_id> \
  /var/www/wallabag/bin/console doctrine:migrations:migrate --env=prod --no-interaction

4.6 Docker Compose 配置（推荐）

使用 docker-compose 可一键部署 wallabag、数据库和 Redis，适合生产环境：

services:
  wallabag:
    image: wallabag/wallabag
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=wallaroot  # 与 db 服务的 root 密码一致
      - SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql
      - SYMFONY__ENV__DATABASE_HOST=db  # 数据库主机（对应 db 服务名）
      - SYMFONY__ENV__DATABASE_PORT=3306
      - SYMFONY__ENV__DATABASE_NAME=wallabag
      - SYMFONY__ENV__DATABASE_USER=wallabag
      - SYMFONY__ENV__DATABASE_PASSWORD=wallapass  # 数据库用户密码
      - SYMFONY__ENV__DATABASE_CHARSET=utf8mb4  # 支持 emoji
      - SYMFONY__ENV__DATABASE_TABLE_PREFIX=wallabag_
      - SYMFONY__ENV__MAILER_DSN=smtp://smtp.example.com:587  # 替换为实际邮件服务器
      - SYMFONY__ENV__FROM_EMAIL=***  # 发件人***
      - SYMFONY__ENV__DOMAIN_NAME=[***]  # 实例 URL
      - SYMFONY__ENV__SERVER_NAME=My Wallabag Instance  # 双因素认证发行者名称
    ports:
      - "80:80"  # 宿主机端口映射（如 8080:80）
    volumes:
      - /opt/wallabag/images:/var/www/wallabag/web/assets/images  # 图片存储卷
    depends_on:
      - db
      - redis

  db:
    image: mariadb
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=wallaroot  # 与 wallabag 服务的 MYSQL_ROOT_PASSWORD 一致
    volumes:
      - /opt/wallabag/db:/var/lib/mysql  # 数据库数据卷
    healthcheck:
      test: ["CMD", "/usr/local/bin/healthcheck.sh", "--innodb_initialized"]
      interval: 20s
      timeout: 3s

  redis:
    image: redis:alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 20s
      timeout: 3s

注意：需根据实际环境修改 MAILER_DSN、FROM_EMAIL、DOMAIN_NAME 等参数。

4.7 Nginx 反向代理配置

通过 Nginx 暴露 HTTPS 服务（需提前申请 SSL 证书）：

server {
    listen 443 ssl;
    server_name wallabag.yourdomain.com;  # 替换为实际域名

    ssl_certificate /etc/letsencrypt/live/wallabag.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wallabag.yourdomain.com/privkey.pem;

    location / {
        proxy_pass [***]  # 代理到 wallabag 容器（或服务名）
        proxy_set_header X-Forwarded-Host $server_name;
        proxy_set_header X-Forwarded-Proto https;  # 传递 HTTPS 协议头
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

4.8 导入 Worker（异步数据导入）

运行 Redis 导入 Worker，支持从第三方平台（如 Pocket、Firefox）导入数据：

docker run --name wallabag-import \
  --link wallabag-db:wallabag-db \
  --link redis:redis \
  -e "MYSQL_ROOT_PASSWORD=my-secret-pw" \
  -e "SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql" \
  -e "SYMFONY__ENV__DATABASE_HOST=wallabag-db" \
  -e "SYMFONY__ENV__DATABASE_NAME=wallabag" \
  -e "SYMFONY__ENV__DATABASE_USER=wallabag" \
  -e "SYMFONY__ENV__DATABASE_PASSWORD=wallapass" \
  wallabag/wallabag import <type>

其中 <type> 为导入类型，可选值：pocket、readability、instapaper、wallabag_v1、wallabag_v2、firefox、chrome。