配置指南¶

Shortener 服务器的完整配置参考。

目录¶

概述
配置文件
环境变量
服务器配置
管理员配置
OIDC 配置
数据库配置
缓存配置
GeoIP 配置

概述¶

Shortener 服务器使用 TOML 格式进行配置。配置可以从以下位置加载：

配置文件（默认：config/config.toml）
环境变量（前缀：SHORTENER__）
命令行参数

优先级（从高到低）：命令行 > 环境变量 > 配置文件

配置文件¶

位置¶

默认位置（按优先级顺序）：

--config 标志指定的路径
./config/config.toml
/etc/shortener/config.toml

格式¶

[server]
# 服务器设置

[shortener]
# 短代码生成设置

[admin]
# 管理员账户设置

[database]
# 数据库连接设置

[cache]
# 缓存设置

[geoip]
# GeoIP 设置

环境变量¶

环境变量使用前缀 SHORTENER__，用双下划线分隔嵌套键：

# 服务器地址
export SHORTENER__SERVER__ADDRESS=":9090"

# 数据库连接 URL（覆盖配置文件的 database.url）
export DATABASE_URL="postgres://user:pass@localhost:5432/shortener?sslmode=require"

# 缓存连接 URL（覆盖配置文件的 cache.url）
export CACHE_URL="redis://:password@localhost:6379/0"

# 启用缓存
export SHORTENER__CACHE__ENABLED="true"

# API 密钥
export SHORTENER__SERVER__API_KEY="your-secret-key"

服务器配置¶

[server]
address = ":8080"                          # 监听地址
site_url = "http://localhost:8080"        # 公共站点 URL
api_key = "your-secret-api-key"           # API 密钥（必需）

详细说明¶

address：服务器监听地址，默认 :8080
site_url：站点的公共 URL，用于生成短链接
api_key：用于认证的 API 密钥，使用 openssl rand -base64 32 生成

短链接配置¶

[shortener]
code_length = 6                           # 短代码长度（4-16）
code_charset = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"

管理员配置¶

管理员账号用于密码登录通道。口令以 Argon2id 哈希（PHC 字符串格式）存储，不以明文保存。

[admin]
username = "admin"                        # 管理员用户名（必需）
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."  # 口令 Argon2id 哈希（必需）

生成哈希（任选其一）：

# 服务端自带的子命令（推荐，无需额外安装 CLI）
shortener-server hash-password --password "your-secure-password"

# 或使用命令行工具
shortener-cli hash-password --password "your-secure-password"

交互式输入（不在 shell 历史中留痕）：

shortener-server hash-password          # 按提示输入口令
shortener-cli hash-password

将输出的整行（$argon2id$...）粘贴为 password_hash 的值。

密码登录与 OIDC 登录为并存的两条独立通道，详见 OIDC 配置。

OIDC 配置¶

通过标准 OIDC / OAuth2.0（授权码流）对接任意身份提供方（IdP），如 Keycloak、Authelia、Okta、Microsoft Entra ID、Google 等。登录时仅白名单内的 IdP 用户可登录。

[oidc]
# IdP 的 issuer 地址（自动发现端点 .well-known/openid-configuration 的前缀）
# 留空表示不启用 OIDC 登录
issuer = "https://keycloak.example.com/realms/shortener"

# 在 IdP 注册的 OAuth2 客户端 ID
client_id = "shortener-app"

# 客户端密钥。可留空（公钥客户端），或通过环境变量 OIDC_CLIENT_SECRET 注入
client_secret = ""

# 在 IdP 注册的回调地址（必须与该 IdP 的配置完全一致）
redirect_uri = "https://shortener.example.com/api/account/oidc/callback"

# 允许登录的用户白名单（email 与/或 sub 任一命中即放行；都为空则放行任意已认证用户）
allow_emails = ["admin@example.com"]
allow_subjects = []

环境变量覆盖¶

敏感配置优先使用环境变量（前缀 SHORTENER__），client_secret 强烈建议通过环境变量注入，避免写入文件：

export OIDC_CLIENT_SECRET="your-client-secret"
# 等价于配置项 [oidc] client_secret

JWT 签名密钥（两条登录通道签发令牌都依赖它）也必须通过环境变量提供：

export JWT_SECRET="$(openssl rand -base64 48)"

在 IdP 侧的配置要点¶

创建 OAuth2 / OIDC 客户端（授权码流，response_type=code）。
将回调地址（Redirect URI / Callback URL）设置为本服务的 https://<你的域名>/api/account/oidc/callback。
申请 openid、profile、email 三个 scope。
若 IdP 要求客户端密钥，将其填入 client_secret 或 OIDC_CLIENT_SECRET。

登录流程¶

访问 GET /api/account/oidc/login?redirect=<前端回跳路径> → 浏览器被重定向到 IdP 授权页。
用户在 IdP 完成认证后，IdP 回调 GET /api/account/oidc/callback?code=...&state=...。
服务用 code 换取 token，校验 id_token 签名，并比对 email/sub 白名单。
校验通过则签发本地 JWT，302 跳回前端并附带 ?token=<jwt>；前端将其存入 localStorage。

前端登录页已内置「使用 OIDC 登录」按钮，点击即触发上述流程。

多实例部署¶

JWT 采用无状态 HS256 签名，只要所有实例使用同一个 JWT_SECRET，即可共享校验、支持横向扩展。

数据库配置¶

数据库连接通过单个 URL 配置，引擎类型（sqlite / postgres / postgresql / mysql）由 URL 的 scheme 自动推断。

[database]
url = "sqlite://data/shortener.db?mode=rwc"  # 连接 URL（必需）
log_level = 1

不同引擎的 url 示例：

SQLite（文件）：sqlite://data/shortener.db?mode=rwc
SQLite（内存，仅测试）：sqlite::memory:
PostgreSQL：postgres://user:pass@localhost:5432/shortener?sslmode=disable
MySQL：mysql://user:pass@localhost:3306/shortener?charset=utf8mb4

缓存配置¶

缓存连接同样通过 URL 配置，引擎（redis / valkey）由 scheme 推断。

[cache]
enabled = true
url = "redis://:password@localhost:6379/0"   # 连接 URL
expire = 3600
prefix = "shorten:"

缓存 URL 示例：

Redis：redis://:password@localhost:6379/0
Valkey：valkey://:password@localhost:6379/0

GeoIP 配置¶

GeoIP 功能用于追踪访问者的地理位置信息。默认禁用，需要手动配置。

[geoip]
enabled = false  # 默认禁用
type = "ip2region"

[geoip.ip2region]
path = "data/ip2region.xdb"
mode = "vector"
version = "4"

启用 GeoIP¶

要启用 GeoIP 功能，需要：

下载 ip2region 数据库文件：

curl -fsSL https://github.com/lionsoul2014/ip2region/raw/master/data/ip2region_v4.xdb \
    -o data/ip2region.xdb

在配置文件中启用：
```
[geoip]
enabled = true
```
重启服务

详细的 GeoIP 配置和使用说明，请参阅 GeoIP 配置指南。

配置示例¶

开发环境¶

[server]
address = ":8080"
site_url = "http://localhost:8080"
api_key = "dev-api-key"

[admin]
username = "admin"
# 生成：shortener-server hash-password "admin123"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$devonly$devonlydevonlydevonlydevonly"

[database]
url = "sqlite://data/shortener.db?mode=rwc"

[cache]
enabled = false

[geoip]
enabled = false

生产环境¶

[server]
address = ":8080"
site_url = "https://short.example.com"
api_key = "${SHORTENER_API_KEY}"

[admin]
username = "${SHORTENER_ADMIN_USER}"
# 生成：shortener-server hash-password "${SHORTENER_ADMIN_PASS}"
password_hash = "${SHORTENER_ADMIN_PASS_HASH}"

[database]
url = "postgres://shortener:${POSTGRES_PASSWORD}@postgres:5432/shortener?sslmode=require"

[cache]
enabled = true
url = "redis://:${REDIS_PASSWORD}@redis:6379/0"

[geoip]
enabled = true

[geoip.ip2region]
path = "/var/lib/shortener/ip2region.xdb"

最佳实践¶

使用环境变量存储敏感数据（密码、API 密钥）
不同环境使用不同配置（开发、生产）
定期轮换 API 密钥和密码
生产环境使用适当的日志级别
启用缓存以提高性能