配置参考

PicFast 支持两种配置方式：config.yaml 或环境变量。环境变量始终优先于 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
  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: "{}"

配置项说明

server

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

jwt

键	类型	默认值	说明
`secret`	string	change-me-in-production	必填。必须修改。使用默认值会导致启动时报错退出。生产环境请使用强随机密钥。
`access_ttl`	duration	15m	Access token 有效期
`refresh_ttl`	duration	168h	Refresh token 有效期（7 天）
`signing_method`	string	HS256	HS256、HS384 或 HS512

app

键	类型	默认值	说明
`name`	string	PicFast	站点名称，显示在页面标题、邮件和 Web UI 中
`site_description`	string	""	Web UI 的 Meta 描述
`favicon_url`	string	""	自定义站点图标 URL；空则使用内置默认图标
`allow_guest_upload`	bool	false	允许不登录上传
`guest_capacity_bytes`	int64	10737418240	所有游客共享的总存储配额（10 GB）
`allow_registration`	bool	true	允许新用户注册。建议创建账号后关闭。
`require_email_verification`	bool	true	登录前必须验证邮箱。仅在 `mail.*` 配置正确且 SMTP 可达时生效。
`audit_upload_logs`	bool	false	记录所有上传操作到审计日志
`user_initial_capacity`	int64	524288000	新用户默认存储配额（500 MB）
`guest_capacity_bytes`	int64	10737418240	所有游客共享的总存储配额（10 GB）
`default_image_ttl`	duration	0（永不过期）	图片默认过期时间（如 `24h`、`168h`；0 = 永不过期）
`guest_image_ttl`	duration	0（永不过期）	游客上传图片的独立过期时间（0 = 使用 `default_image_ttl`；可设为 `24h` 等较短时间）
`admin_email`	string	""	与 `admin_password` 同时设置后，首次启动自动创建管理员并跳过初始化向导
`admin_password`	string	""	自动创建的管理员账号密码
`moderation_mode`	string	disabled	`"disabled"`（默认关闭）、`"manual"`（人工审核）
`footer_text_1`	string	""	可选页脚文字行 1；空则不显示
`footer_link_1`	string	""	可选页脚文字行 1 的链接
`footer_text_2`	string	""	可选页脚文字行 2；空则不显示
`footer_link_2`	string	""	可选页脚文字行 2 的链接
`icp_number`	string	""	ICP 备案号（适用于在中国大陆托管服务的站点）
`icp_link`	string	https://beian.miit.gov.cn/	ICP 备案链接地址
`psb_number`	string	""	公安备案号
`psb_link`	string	""	公安备案链接地址
`analytics_provider`	string	""	""（关闭）、`"plausible"`、`"umami"`、`"ga4"`、`"baidu"`、`"custom"`
`analytics_config`	json	""	各服务商的独立配置（详见下方「统计分析」章节）

统计分析服务

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

键	类型	默认值	说明
`host`	string	""	SMTP 服务器地址
`port`	int	1025	SMTP 端口（587 = STARTTLS，465 = TLS，1025 = 本地 Mailpit）
`encryption`	string	none	`"starttls"`、`"tls"` 或 `"none"`
`from_email`	string	noreply@picfast.local	发件人地址；配置 SMTP 时必须填写
`from_name`	string	PicFast	发件人显示名称

关于邮箱验证

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

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

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

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