BingPaper/CONFIG.md

配置指南

BingPaper 支持通过配置文件（YAML）和环境变量进行配置。

配置文件

程序启动时默认会查找当前目录下的 config.yaml 或 data/config.yaml。如果不存在，会自动在 data/config.yaml 创建一份带有默认值的配置文件。

你可以通过命令行参数 -config 或 -c 指定配置文件路径：

./BingPaper -c my_config.yaml

完整配置说明

以下是 config.example.yaml 的详细说明：

server (服务配置)

• port: 服务监听端口，默认 8080。
• base_url: 服务的基础 URL，用于生成某些绝对路径，默认为空。

log (日志配置)

• level: 业务日志级别，可选 debug, info, warn, error，默认 info。
• filename: 业务日志输出文件路径，默认 data/logs/app.log。
• db_filename: 数据库日志输出文件路径，默认 data/logs/db.log。
• max_size: 日志文件切割大小 (MB)，默认 100。
• max_backups: 保留旧日志文件个数，默认 3。
• max_age: 保留旧日志文件天数，默认 7。
• compress: 是否压缩旧日志文件，默认 true。
• log_console: 是否同时输出到控制台，默认 true。
• show_db_log: 是否在控制台输出数据库日志（SQL），默认 false。
• db_log_level: 数据库日志级别，可选 debug, info, warn, error, silent。debug/info 会记录所有 SQL。默认 info。

api (API 模式)

• mode: API 行为模式。
  • local: (默认) 接口直接返回图片的二进制流，适合图片存储对外部不可见的情况。
  • redirect: 接口返回 302 重定向到图片的 PublicURL，适合配合 S3 或 WebDAV 的公共访问。
• enable_mkt_fallback: 当请求的地区不存在或无数据时，是否允许兜底回退到默认地区或任意可用地区，默认 true。

cron (定时任务)

• enabled: 是否启用定时抓取，默认 true。
• daily_spec: Cron 表达式，定义每日抓取时间。默认 "0 10 * * *" (每日上午 10:00)。

fetcher (抓取配置)

• regions: 需要抓取的地区编码列表（如 zh-CN, en-US 等）。如果不设置，默认为包括主要国家在内的 17 个地区。

retention (数据保留)

• days: 图片及元数据保留天数。超过此天数的数据可能会被清理任务处理。设置为 0 表示永久保留，不进行自动清理。默认 0。

db (数据库配置)

• type: 数据库类型，可选 sqlite, mysql, postgres。默认 sqlite。
• dsn: 数据库连接字符串。
  • SQLite: data/bing_paper.db (默认)
  • MySQL 示例: user:pass@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local
  • Postgres 示例: host=localhost user=user password=pass dbname=db port=5432 sslmode=disable TimeZone=Asia/Shanghai

注意： BingPaper 支持数据库配置的热更新。如果你在程序运行时修改了 db.type 或 db.dsn，程序会自动尝试将当前数据库中的所有数据（图片记录、变体信息、Token）迁移到新的数据库中。

• 在迁移开始前，程序会清空目标数据库中的相关表以防止数据冲突。
• 迁移过程在事务中执行，确保数据一致性。
• 迁移完成后，程序将无缝切换到新的数据库连接。

storage (存储配置)

• type: 存储类型，可选 local, s3, webdav。默认 local。
• local (本地存储):
  • root: 图片存储根目录，默认 data/picture。
• s3 (对象存储):
  • endpoint: S3 端点（如 s3.amazonaws.com 或 MinIO 地址）。
  • region: 区域（如 us-east-1）。
  • bucket: 桶名称。
  • access_key: 访问密钥 ID。
  • secret_key: 私有访问密钥。
  • public_url_prefix: 公网访问前缀，若为空则由 SDK 自动尝试生成。
  • force_path_style: 是否强制使用路径样式（MinIO 等通常需要设为 true）。
• webdav (WebDAV 存储):
  • url: WebDAV 服务器地址。
  • username: 用户名。
  • password: 密码。
  • public_url_prefix: 公网访问前缀。

admin (管理配置)

• password_bcrypt: 管理员密码的 Bcrypt 哈希值。默认密码为 admin123，对应哈希 $2a$10$fYHPeWHmwObephJvtlyH1O8DIgaLk5TINbi9BOezo2M8cSjmJchka。
  • 强烈建议修改此项。

token (认证配置)

• default_ttl: 管理后台登录 Token 的默认有效期，默认 168h (7天)。

feature (功能开关)

• write_daily_files: 是否在每日目录下写入原始文件（不仅是数据库记录），默认 true。

web (静态资源)

• path: 自定义管理后台前端文件的存放路径，默认 web。若指定路径不存在，将尝试使用内置的嵌入页面。

---

环境变量配置

所有的配置项都可以通过环境变量进行覆盖。环境变量前缀为 BINGPAPER_，层级之间使用下划线 _ 分隔。

常用示例：

• BINGPAPER_SERVER_PORT=9090
• BINGPAPER_DB_TYPE=mysql
• BINGPAPER_DB_DSN="user:pass@tcp(127.0.0.1:3306)/bingpaper"
• BINGPAPER_STORAGE_TYPE=s3
• BINGPAPER_STORAGE_S3_BUCKET=my-images
• BINGPAPER_ADMIN_PASSWORD_BCRYPT="$2a$10$..."
• HOST_PORT=8080 (仅限 Docker Compose 部署，控制宿主机映射到外部的端口)
• BINGPAPER_SERVER_PORT=8080 (控制应用监听端口及容器内部端口)