PicHost/docs-site/guide/configuration.md

PicHost 支持通过环境变量（Docker / .env）与后台 设置 页配置。管理员在 设置与偏好（/settings）左侧切换 基础设置、域名与路径、访问控制、标签管理、操作日志；多数项 SQLite 优先；部分项环境变量可覆盖或锁定后台编辑。

优先级总览

配置项	优先级（高 → 低）	环境变量覆盖后台
API 上传 Token	环境变量 → SQLite	是（设了则后台无法重新生成）
WebP 质量	SQLite → 环境变量 → 默认 80	否（未在 DB 存时读 env）
防盗链白名单	SQLite → 环境变量	否
网站 / 图片域名	SQLite → 环境变量（设置 API 配置值）；直链生成另用 effective* 或请求 origin	否
简短图片链接	SQLite → 环境变量 → 默认 false	否
按年/月分组存储	SQLite → 环境变量 → 默认 true	否
全局自动删除天数	SQLite → 环境变量 → 默认 0	否
登录人机验证	SQLite（设置 → 访问控制）	否

变量说明

API_UPLOAD_TOKEN

外部脚本上传 Token（Twikoo / 油猴 / 博客）。请求头：Auth-Token: <token>；表单上传仍可用 token 字段。

• 未配置时可在后台 API 页生成
• 环境变量一旦设置，优先级最高，后台显示「由环境变量覆盖」且无法重新生成
• 别名：NUXT_API_UPLOAD_TOKEN

ALLOWED_REFERER_HOSTS

防盗链白名单，逗号分隔域名。自身域名自动放行。可选；不填可在设置页配置。若环境变量有值且 SQLite 未存，则使用环境变量。

SITE_BASE_URL / IMAGE_BASE_URL

• 网站域名：管理后台、API、Twikoo 上传入口
• 图片域名：复制链接与直链使用的公网地址

双域名分离需两者主机名不同，详见 双域名分离 与 Cloudflare / CF 优选部署。填写后须与反代 server_name 一致；勿通过 localhost、IP 或未配置的域名访问生产后台。

在后台 设置 中保存时须显式勾选「启用后台与图片域名分离」，并同时填写两个域名；关闭双域名会清除网站域配置（需确认）。设置 API 返回的配置值与「当前生效」直链地址已分离，详见 更新日志。

HIDE_FOLDER_IN_URL

true 时使用简短图片链接（仅域名 + 文件名，如 img.example.com/a8K3xP.webp）；false 时保留日期或自定义目录（如 img.example.com/2026/08/a8K3xP.webp）。对外 URL 不会 暴露内部 images/ 前缀；旧版含 images/ 的直链仍兼容。

STORAGE_USE_DATE_PATH / STORAGE_LAYOUT

• STORAGE_USE_DATE_PATH=true（默认）或 STORAGE_LAYOUT=date：新图保存为 images/年/月/随机ID.webp
• false 或 STORAGE_LAYOUT=flat：保存为 images/随机ID.webp

也可在设置页切换。

DATA_DIR

图片与 SQLite 根目录。默认 ./data，容器内为 /data。

WEBP_QUALITY

服务端 WebP 压缩质量 1–100，默认 80。

AUTO_DELETE_DAYS

全局自动删除超过 N 天的图片，0 表示关闭。启用后仅影响之后新上传的图片（与按用户策略一致）。也可在设置页配置。

DEV_BYPASS_ACCESS

仅本地开发：true 绕过登录验证。生产环境勿用。

登录人机验证（仅后台设置）

在 设置 → 访问控制 配置，存入 SQLite，无对应环境变量：

方式	说明
本地滑块（默认）	无需第三方服务
Cloudflare Turnstile	填写 Site Key 与 Secret Key
Cap	填写 API Endpoint 与 Secret

登录与注册共用同一验证方式。若第三方配置错误导致无法登录，执行 docker exec pichost slider（或 npm run slider）恢复为本地滑块。

存储后端（可选）

管理员通常在 存储 页添加后端；也可用环境变量引导（如 STORAGE_BACKEND=s3 与 S3_*）。详见 存储。

Docker Compose 示例

services:
  pichost:
    image: muxui/pichost:latest
    ports:
      - "6892:6892"
    volumes:
      - ./data:/data
    environment:
      SITE_BASE_URL: https://admin.example.com
      IMAGE_BASE_URL: https://pic.example.com
      API_UPLOAD_TOKEN: your-secret-token
      WEBP_QUALITY: "85"

修改环境变量后需 重启容器 才能生效（Token、质量等读取在启动时或请求时按实现读取）。

与后台设置对照

后台设置项	对应环境变量
API Token	API_UPLOAD_TOKEN
防盗链	ALLOWED_REFERER_HOSTS
网站域名	SITE_BASE_URL
图片域名	IMAGE_BASE_URL
隐藏目录前缀	HIDE_FOLDER_IN_URL
按年/月分组	STORAGE_USE_DATE_PATH / STORAGE_LAYOUT
WebP 质量	WEBP_QUALITY
自动删除	AUTO_DELETE_DAYS
登录验证	（仅后台 设置 → 访问控制）

完整模板见仓库根目录 .env.example。