配置参考

PicFast 支持两种配置方式：config.yaml 或 PICFAST_ 前缀的环境变量。环境变量始终优先于 YAML 配置。

完整示例（config.yaml）

server:
  port: 8080
  base_url: "http://localhost:8080"
  web_dir: ""
  pprof_enabled: false

database:
  url: "postgres://picfast:picfast@localhost:5432/picfast?sslmode=disable"

jwt:
  secret: "change-me-in-production"
  access_ttl: 15m
  refresh_ttl: 168h
  signing_method: "HS256"

storage:
  local_root: "./data/uploads"
  thumbnail_dir: "./data/thumbnails"

mail:
  host: "127.0.0.1"
  port: 1025
  username: ""
  password: ""
  from_email: "noreply@picfast.local"
  from_name: "PicFast"
  encryption: "none"

app:
  name: "PicFast"
  site_description: "PicFast is a modern self-hosted image hosting service."
  favicon_url: ""
  allow_guest_upload: false
  allow_registration: true
  allow_oauth_registration: true
  allow_user_image_processing: true
  skip_image_processing: false
  require_email_verification: true
  audit_upload_logs: false
  user_initial_capacity: 524288000
  guest_capacity_bytes: 10737418240
  default_image_ttl: "0"
  guest_image_ttl: "0"
  admin_email: ""
  admin_password: ""
  moderation_mode: "disabled"
  footer_text_1: ""
  footer_link_1: ""
  footer_text_2: ""
  footer_link_2: ""
  icp_number: ""
  icp_link: "https://beian.miit.gov.cn/"
  psb_number: ""
  psb_link: ""
  analytics_provider: ""
  analytics_config: "{}"

配置项参考

database

Key	环境变量	类型	默认值	说明
`url`	`PICFAST_DATABASE_URL`	string	—	PostgreSQL 连接串（必填）

server

Key	环境变量	类型	默认值	说明
`port`	`PICFAST_SERVER_PORT`	int	8080	监听端口
`base_url`	`PICFAST_SERVER_BASE_URL`	string	http://localhost:8080	服务公开访问地址。验证邮件链接和 ShareX 配置依赖此值，必须设为实际访问域名。
`web_dir`	`PICFAST_SERVER_WEB_DIR`	string	""	前端静态文件目录（可选；自动检测 `web-dist/` 和 `web/dist/`）
`pprof_enabled`	`PICFAST_SERVER_PPROF_ENABLED`	bool	false	开启 Go pprof 端点（`/api/v1/admin/debug/pprof/*`，仅管理员可用）

storage

Key	环境变量	类型	默认值	说明
`local_root`	`PICFAST_STORAGE_LOCAL_ROOT`	string	"./data/uploads"	本地存储后端的文件根目录
`thumbnail_dir`	`PICFAST_STORAGE_THUMBNAIL_DIR`	string	"./data/thumbnails"	缩略图生成目录

jwt

Key	环境变量	类型	默认值	说明
`secret`	`PICFAST_JWT_SECRET`	string	change-me-in-production	必填。必须修改。使用默认值会导致启动时报错。
`access_ttl`	`PICFAST_JWT_ACCESS_TTL`	duration	15m	Access token 有效期
`refresh_ttl`	`PICFAST_JWT_REFRESH_TTL`	duration	168h	Refresh token 有效期（7 天）
`signing_method`	`PICFAST_JWT_SIGNING_METHOD`	string	HS256	HS256、HS384 或 HS512

app

Key	环境变量	类型	默认值	说明
`name`	`PICFAST_APP_NAME`	string	PicFast	站点名称，显示在页面标题、邮件和 Web UI 中
`web_base_url`	`PICFAST_APP_WEB_BASE_URL`	string	""	登录后用户跳转的前端地址。空时回退到 `server.base_url`。启用 OAuth 时必填。
`site_description`	`PICFAST_APP_SITE_DESCRIPTION`	string	""	Web UI 的 Meta 描述
`favicon_url`	`PICFAST_APP_FAVICON_URL`	string	""	自定义站点图标 URL；空则使用内置默认图标
`allow_guest_upload`	`PICFAST_APP_ALLOW_GUEST_UPLOAD`	bool	false	允许不登录上传
`guest_capacity_bytes`	`PICFAST_APP_GUEST_CAPACITY_BYTES`	int64	10737418240	所有游客共享的总存储配额（10 GB）
`allow_registration`	`PICFAST_APP_ALLOW_REGISTRATION`	bool	false	允许新用户注册。建议创建账号后关闭。
`allow_oauth_registration`	`PICFAST_APP_ALLOW_OAUTH_REGISTRATION`	bool	false	允许通过 OAuth/OIDC 登录创建新账户。当邮箱注册关闭但此项开启时，登录页仅显示 OAuth/OIDC 登录入口。
`allow_user_image_processing`	`PICFAST_APP_ALLOW_USER_IMAGE_PROCESSING`	bool	true	允许用户对单张图片启用压缩 / 水印等处理
`skip_image_processing`	`PICFAST_APP_SKIP_IMAGE_PROCESSING`	bool	false	跳过所有图片处理，直接保存原始文件。开启后用户图片处理设置会被隐藏且忽略。
`max_upload_bytes`	`PICFAST_APP_MAX_UPLOAD_BYTES`	int64	52428800	默认单文件上传限制（50 MB），分组级别的限制可覆盖此值
`require_email_verification`	`PICFAST_APP_REQUIRE_EMAIL_VERIFICATION`	bool	false	登录前必须验证邮箱。仅在 SMTP 配置正确且可达时生效。
`audit_upload_logs`	`PICFAST_APP_AUDIT_UPLOAD_LOGS`	bool	false	记录所有上传操作到审计日志
`user_initial_capacity`	`PICFAST_APP_USER_INITIAL_CAPACITY`	int64	524288000	新用户默认存储配额（500 MB）
`default_image_ttl`	`PICFAST_APP_DEFAULT_IMAGE_TTL`	duration	0（永不过期）	图片默认过期时间（如 `24h`、`168h`；0 = 永不过期）
`guest_image_ttl`	`PICFAST_APP_GUEST_IMAGE_TTL`	duration	0（永不过期）	游客上传图片的独立过期时间（0 = 使用 `default_image_ttl`）
`admin_email`	`PICFAST_APP_ADMIN_EMAIL`	string	""	与 `admin_password` 同时设置后，自动创建管理员并跳过初始化向导
`admin_password`	`PICFAST_APP_ADMIN_PASSWORD`	string	""	自动创建的管理员账号密码
`moderation_mode`	`PICFAST_APP_MODERATION_MODE`	string	disabled	`"disabled"`（默认关闭）、`"manual"`（人工审核）
`footer_text_1`	`PICFAST_APP_FOOTER_TEXT_1`	string	""	可选页脚文字行 1；空则不显示
`footer_link_1`	`PICFAST_APP_FOOTER_LINK_1`	string	""	可选页脚文字行 1 的链接
`footer_text_2`	`PICFAST_APP_FOOTER_TEXT_2`	string	""	可选页脚文字行 2；空则不显示
`footer_link_2`	`PICFAST_APP_FOOTER_LINK_2`	string	""	可选页脚文字行 2 的链接
`icp_number`	`PICFAST_APP_ICP_NUMBER`	string	""	ICP 备案号（适用于在中国大陆托管服务的站点）
`icp_link`	`PICFAST_APP_ICP_LINK`	string	https://beian.miit.gov.cn/	ICP 备案链接地址
`psb_number`	`PICFAST_APP_PSB_NUMBER`	string	""	公安备案号
`psb_link`	`PICFAST_APP_PSB_LINK`	string	""	公安备案链接地址
`theme_config`	`PICFAST_APP_THEME_CONFIG`	json	""	主题覆盖配置（Logo、配色等），JSON 格式
`default_copy_format`	`PICFAST_APP_DEFAULT_COPY_FORMAT`	string	"markdown"	上传页默认选中的复制格式：`url`、`markdown`、`html`、`bbcode`
`copy_template`	`PICFAST_APP_COPY_TEMPLATE`	string	""	可选的自定义复制模板（如 `![image]({url})`）
`analytics_provider`	`PICFAST_APP_ANALYTICS_PROVIDER`	string	""	""（关闭）、`"plausible"`、`"umami"`、`"ga4"`、`"baidu"`、`"custom"`
`analytics_config`	`PICFAST_APP_ANALYTICS_CONFIG`	json	""	各服务商的独立配置（详见「统计分析服务」章节）

oauth

Key	环境变量	类型	说明
`providers`	`PICFAST_OAUTH_PROVIDERS`	array	OAuth / OIDC 提供商列表。详见 OAuth 文档。
`providers[].id`	—	string	唯一标识（如 `"github"`、`"keycloak"`）
`providers[].display_name`	—	string	登录按钮上显示的名称
`providers[].type`	—	string	`"oidc"` 或 `"github"`
`providers[].client_id`	—	string	提供商的 OAuth Client ID
`providers[].client_secret`	—	string	提供商的 OAuth Client Secret
`providers[].issuer`	—	string	`type: oidc` 时必填。OIDC issuer URL，用于校验 ID token 的 `iss` 声明，并默认用于发现端点。
`providers[].auth_url`	—	string	OAuth 授权端点。不支持 discovery 时需与 `token_url`、`jwks_url` 一起配置。
`providers[].token_url`	—	string	OAuth token 端点。不支持 discovery 时与 `auth_url` 一起必填。
`providers[].userinfo_url`	—	string	OIDC userinfo 端点。可选，覆盖任意模式下的默认端点。
`providers[].scopes`	—	[]string	OAuth scopes，默认 `[openid, profile, email]`
`providers[].jwks_url`	—	string	JWKS 端点地址，未填则从 `issuer` 自动发现
`providers[].enabled`	—	bool	是否启用此提供商

统计分析服务

PicFast 支持接入统计服务来追踪 Web UI 的访问情况。通过 app.analytics_provider 和 app.analytics_config 进行配置。

`plausible`	`domain`（必填），`server_url`（可选）
`umami`	`website_id`（必填），`script_url`（必填）
`ga4`	`measurement_id`（必填）
`baidu`	`site_id`（必填）
`custom`	`script_html`（原始 HTML/脚本字符串，会注入到每个页面中）

mail

Key	环境变量	类型	默认值	说明
`host`	`PICFAST_MAIL_HOST`	string	""	SMTP 服务器地址
`port`	`PICFAST_MAIL_PORT`	int	1025	SMTP 端口（587 = STARTTLS，465 = TLS，1025 = 本地 Mailpit）
`username`	`PICFAST_MAIL_USERNAME`	string	""	SMTP 用户名
`password`	`PICFAST_MAIL_PASSWORD`	string	""	SMTP 密码
`encryption`	`PICFAST_MAIL_ENCRYPTION`	string	none	`"starttls"`、`"tls"` 或 `"none"`
`from_email`	`PICFAST_MAIL_FROM_EMAIL`	string	noreply@picfast.local	发件人地址；配置 SMTP 时必须填写
`from_name`	`PICFAST_MAIL_FROM_NAME`	string	PicFast	发件人显示名称

关于邮箱验证

默认注册成功后立即登录。如需启用邮箱验证：

配置 mail.* 为有效的 SMTP 服务器
设置 app.require_email_verification = true

如果设置了邮箱验证但 SMTP 不可达，系统会退回普通注册流程，并在启动日志中输出警告。

本地开发推荐使用内置的 Mailpit（端口 1025 SMTP / 8025 Web UI），所有邮件都会拦截到本地收件箱，不会真的发到外部邮箱。