🚀 使用 Docker Compose 部署 Picsur 图床服务

Picsur 是一款开源的、易于自托管的图片分享服务，类似于 Imgur，并内置了强大的图片转换与编辑功能。它支持多种图像格式，提供了丰富的管理选项，非常适合个人或团队用于图像托管与分享。

下面为大家带来基于 Docker Compose 的 Picsur 部署教程。

📦 项目简介

Picsur 是一个功能丰富的自托管图像共享服务，主要特点包括：

功能类别	具体说明
核心功能	图片上传与查看（支持匿名及注册用户）、内置图像转换与格式转换、基础图像编辑（旋转、翻转、调整大小等）
格式支持	支持 QOI, JPG, PNG, WEBP (动图), TIFF, BMP, GIF (动图) 等多种格式
管理与安全	用户角色与权限管理、自动剥离图片 EXIF 信息保护隐私、可设置图片过期时间、CORS 跨域限制
部署与集成	提供 Docker 镜像、支持 ShareX 上传、可选保留原始图片

📋 部署前准备

环境要求 确保你的服务器已安装 Docker 和 Docker Compose。可以通过在终端执行 docker -v 和 docker compose version 来验证。建议使用较新版本的 Docker，例如 26.1.3 及以上，Docker Compose 版本为 v2.27.1 及以上。
资源检查
- 端口：确认计划使用的端口（如教程中的 18003）未被其他程序占用。
- 磁盘空间：确保挂载目录（如示例中的 /mnt/10t/file/Database/picsur-data）有足够空间存储图片和数据库。
网络：如果通过域名访问，请提前完成域名解析。

⚙️ 配置 Docker Compose

1.创建项目目录创建一个目录（如 picsur）用于存放所有相关文件，并进入该目录。

    mkdir -p /path/to/your/picsur && cd /path/to/your/picsur

2.创建 docker-compose.yml 文件将以下配置内容粘贴到新创建的 docker-compose.yml 文件中。此配置定义了 Picsur 应用及其依赖的 PostgreSQL 数据库。

#version: '3'
services:
  # 1. Picsur 应用服务
  picsur:
    image: ghcr.io/caramelfur/picsur:latest  # 官方最新镜像
    container_name: picsur
    ports:
      - 18003:8080   # 端口映射：主机 18003 → 容器 8080（可修改主机端口，如 8003:8080）
    #volumes: #挂载上去也没用。
     #- ./picsur:/picsur
    environment:
      PICSUR_HOST: 0.0.0.0  # 监听所有网络接口
      PICSUR_PORT: 8080  # 容器内服务端口（固定，与端口映射的容器端一致）
      # 数据库连接配置（需与 picsur_postgres 服务参数匹配）
      PICSUR_DB_HOST: picsur_postgres  # 数据库容器名（固定，通过容器网络访问）
      PICSUR_DB_PORT: 5432  # PostgreSQL 默认端口
      PICSUR_DB_USERNAME: picsur  # 数据库用户名（与下方 POSTGRES_USER 一致）
      PICSUR_DB_PASSWORD: your_db_password  # 必须与下方 POSTGRES_PASSWORD 一致！
      PICSUR_DB_DATABASE: picsur  # 数据库名（与下方 POSTGRES_DB 一致）
      ## 默认管理员账户是 admin, 这个没法改，密码就是下面这个你设置的
      #PICSUR_ADMIN_PASSWORD: admin. #用户密码
      # 管理员账户配置（默认用户名为 admin，密码在此设置）
      PICSUR_ADMIN_PASSWORD: your_admin_password  # 必须修改！默认密码不安全（如 Picsur@2024!）
      # 可选：JWT 密钥（用于接口安全，未设置则自动生成）
      # PICSUR_JWT_SECRET: your_random_string  # 建议设置，如 openssl rand -hex 16 生成 #CHANGE_ME
      # PICSUR_JWT_EXPIRY: 7d  # JWT 过期时间（默认7天）

      # 最大上传文件大小（默认128MB，单位字节，128*1024*1024=134217728）
      PICSUR_MAX_FILE_SIZE: 128000000   # 128MB，可修改（如 268435456 为256MB）
      ## No need to touch this, unless you use a custom frontend
      # PICSUR_STATIC_FRONTEND_ROOT: "/picsur/frontend/dist"
      ## Warning: Verbose mode might log sensitive data
      # PICSUR_VERBOSE: "true"
    restart: unless-stopped  # 容器退出后自动重启（非总是重启，手动停止后不自动启动）
  # 2. PostgreSQL 数据库服务（存储图片元数据）
  picsur_postgres:
    image: postgres:14-alpine  # 轻量 Alpine 版本，适合存储元数据
    container_name: picsur_postgres
    environment:
      POSTGRES_DB: picsur  # 数据库名（与上方 PICSUR_DB_DATABASE 一致）
      POSTGRES_PASSWORD: your_db_password  # 必须与上方 PICSUR_DB_PASSWORD 一致！
      POSTGRES_USER: picsur  # 数据库用户名（与上方 PICSUR_DB_USERNAME 一致）
    restart: unless-stopped
    volumes:
      # 数据库数据持久化（替换为你的目录，确保存在且有权限）
      # 示例1：当前目录下的 picsur-data
      - ./picsur-data:/var/lib/postgresql/data # 默认数据存放在当前文件夹下的picsur-data目录中，可以自行修改
      # 示例2：用户配置中的自定义路径（需确保/mnt/10t/...存在）
      #- /mnt/10t/file/Database/picsur-data:/var/lib/postgresql/data


   #访问ip:18003，登录账密是"admin"和PICSUR_ADMIN_PASSWORD的密码，设置里面有缓存期限默认7D天后删除。

3.关键配置说明 * 端口映射：18003:8080 表示将宿主机的 18003 端口映射到 Picsur 容器的 8080 端口。你可以按需修改宿主机的端口。 * 数据库密码：务必确保 PICSUR_DB_PASSWORD（Picsur 服务连接数据库的密码）与 POSTGRES_PASSWORD（数据库自身密码）完全一致，否则 Picsur 将无法连接数据库。 * 数据持久化：volumes 部分将数据库数据挂载到宿主机路径，防止容器重启后数据丢失。请确保路径存在且有写权限。 * 管理员密码：PICSUR_ADMIN_PASSWORD 是你后续登录 Picsur 后台的密码。 * 镜像来源：Picsur 的官方镜像托管在 ghcr.io（GitHub Container Registry），而非 Docker Hub。

🚀 启动与验证

1.启动服务在 docker-compose.yml 文件所在目录下，执行以下命令来后台启动服务：

    docker-compose up -d

此命令会拉取镜像并创建和启动容器。

2.检查服务状态使用以下命令查看容器是否正常运行：

    docker-compose ps

如果状态（State）栏显示为 Up，则表明容器已成功启动。

3.查看日志如果容器启动异常，可以通过日志来排查问题：

    docker-compose logs picsur  # 查看Picsur应用日志

4.访问服务在浏览器中输入 http://你的服务器IP:18003。如果看到 Picsur 的主界面，说明服务已成功部署。

🔧 基础配置与使用

初始登录
- 点击页面右上角的 Login 按钮。
- 用户名 固定为 admin。
- 密码是你在 docker-compose.yml 中设置的 PICSUR_ADMIN_PASSWORD（示例中为 aaaaaa-.）。
上传与分享图片
- 登录后，直接将图片拖拽到页面即可上传。
- 上传后，系统会提供该图片在不同格式（如 Markdown、HTML）下的直链，方便你在其他地方引用。
重要设置
- 保留原图：默认情况下，Picsur 不会保留原始图像文件以节省空间。如需保留，可在 Settings -> General 中启用 Keep original file。注意：原图的 EXIF 信息不会被自动清除，可能包含敏感信息（如地理位置）。
- 开放注册：默认禁止用户注册。如需开放注册，需进入 Settings -> Roles -> Guest -> Edit，为访客角色勾选 Register 权限，保存后登录页面即会出现注册按钮。
- 设置图片过期时间：上传图片时或之后，可以设置图片的有效期，过期后图片将被自动删除。

🔧 基础配置与使用2

Picsur 核心操作围绕 “上传图片→管理图片→分享图片”，新手可按以下步骤快速上手：

1. 步骤 1：上传图片

登录后点击主界面 “上传图片” 按钮（或拖拽图片到界面）；
选择本地图片（支持单张或多张，大小不超过 PICSUR_MAX_FILE_SIZE 限制）；
上传完成后，图片会显示在列表中，包含预览图、文件名、大小、上传时间。

2. 步骤 2：管理图片

查看详情：点击图片预览，可查看原图、复制图片链接（用于分享）；
设置过期时间：点击图片右侧 “编辑” 按钮，修改 “过期时间”（如 1 天、30 天），到期后自动删除；
删除图片：点击 “删除” 按钮，立即移除图片（数据库与存储中均删除）。

3. 步骤 3：系统设置（管理员权限）

点击右上角 “设置” 图标，可配置核心参数：

默认过期时间：修改新上传图片的默认过期时间（如改为 30 天）；
最大文件大小：若未在配置文件中设置，可在此处调整（需重启服务生效）；
JWT 配置：重新生成或修改 JWT 密钥，增强接口安全性。

4. 步骤 4：分享图片

点击图片右侧 “链接” 按钮，复制生成的图片 URL（如 http://服务器IP:18003/i/abc123）；
将链接分享给他人，对方可直接通过浏览器访问图片（无需登录）；
若图片设置了过期时间，到期后链接失效。

🔄 维护与管理

1.更新服务当有新版本发布时，可按以下步骤更新：

    # 进入docker-compose.yml所在目录
    cd /path/to/your/picsur
    # 停止并移除当前容器
    docker-compose down
    # 拉取最新的Picsur镜像
    docker-compose pull
    # 重新创建并启动容器
    docker-compose up -d
    # 清理无用的旧镜像
    docker image prune

2.数据备份定期备份数据库挂载卷（示例中的 /mnt/10t/file/Database/picsur-data）即可备份所有图片数据。

3.卸载服务如需卸载 Picsur，在项目目录下执行：

    docker-compose down

如果希望彻底删除所有数据（包括数据库），在上述命令后移除挂载的目录即可。

🔄 维护与管理2

（2）备份图片文件（关键！默认未挂载）

默认配置中图片存储在 picsur 容器的 /app/uploads 目录，需手动复制到本地（或修改配置挂载该目录）：

# 临时备份图片到本地 picsur-uploads 目录
mkdir -p picsur-uploads
docker cp picsur:/app/uploads ./picsur-uploads

推荐优化：修改 picsur 服务的 volumes，添加图片目录挂载（避免容器删除后图片丢失）：

    volumes:
      - ./picsur-uploads:/app/uploads  # 图片文件持久化

3. 更新 Picsur 版本

# 1. 拉取最新镜像
docker compose pull

# 2. 重启服务，应用更新（数据不丢失）
docker compose up -d

4. 修改配置参数（如最大上传大小）

1.编辑 docker-compose.yml，修改目标参数（如 PICSUR_MAX_FILE_SIZE: 268435456 即 256MB）； 2.重启服务生效：

    docker compose restart

🐛 常见问题排查

问题现象	可能原因与解决方案
容器启动失败	1. 检查 `docker-compose.yml` 文件语法是否正确。 2. 执行 `docker-compose logs` 查看具体错误日志。
无法访问网页	1. 确认服务器防火墙是否开放了 `18003` 端口。 2. 检查 `docker-compose ps` 确认容器是否在运行状态。
数据库连接失败	1. 最常见原因：`PICSUR_DB_PASSWORD` 和 `POSTGRES_PASSWORD` 设置不一致。 2. 确保 `picsur_postgres` 容器先于 `picsur` 容器启动并正常运行。
上传图片失败	1. 检查 `PICSUR_MAX_FILE_SIZE` 设置，确保上传文件未超出大小限制。 2. 检查宿主机和数据库挂载目录的磁盘空间是否充足。
权限问题	如果遇到文件操作权限错误（例如在数据库初始化时），可能需要检查并调整宿主机挂载目录的权限，确保容器内进程（通常以非root用户运行）有读写权限。

希望这篇教程能帮助你顺利搭建属于自己的图床服务！如果在部署过程中遇到其他问题，Picsur 的 GitHub 项目页面是寻求解决方案的好去处。

🐛 常见问题排查2

1. 登录失败（提示 “用户名或密码错误”）

原因 1：输入的密码与 PICSUR_ADMIN_PASSWORD 不一致。解决：确认配置中的密码，注意区分大小写（如 Picsur123 与 picsur123 不同）。
原因 2：数据库连接失败，无法验证管理员账户。解决：检查数据库密码是否一致，重启数据库容器：docker compose restart picsur_postgres。

2. 上传图片失败（提示 “文件过大”）

原因：图片大小超过 PICSUR_MAX_FILE_SIZE 限制。

解决： 1. 编辑 docker-compose.yml，增大 PICSUR_MAX_FILE_SIZE（单位字节，如 256MB=268435456）； 2. 重启服务：docker compose restart picsur。

3. 图片无法访问（404 错误）

原因 1：图片已过期并被自动清理。解决：上传新图片，或延长过期时间（编辑图片设置）。
原因 2：容器内图片文件丢失（如容器重建未挂载图片目录）。解决：恢复备份的图片文件到 /app/uploads（或重新上传），并配置 volumes: - ./picsur-uploads:/app/uploads 持久化。

4. 数据库连接频繁断开（日志显示 “connection reset”）

原因：PostgreSQL 容器内存不足或被意外终止。

解决： 1. 检查服务器内存使用：free -m，若内存不足需扩容； 2. 重启数据库与应用容器：docker compose restart。

5. 容器重启后图片丢失

原因：未挂载图片存储目录（/app/uploads），容器重建后内部文件丢失。

解决： 1.编辑 docker-compose.yml，添加图片目录挂载：

        volumes:
          - ./picsur-uploads:/app/uploads

2.重启服务：docker compose up -d，后续上传的图片会保存在本地 picsur-uploads 目录。

通过以上步骤，新手可快速部署 Picsur 并实现图片管理功能。Picsur 适合个人搭建私有图床，也可作为团队内部临时图片分享工具，后续可根据需求扩展存储路径（如挂载 NAS）或配置反向代理（添加 HTTPS），具体参考 Picsur 官方文档。