Pagure 5.14.1 配置参数详解

目标：逐项解释 Pagure 5.14.1 的配置体系——配置加载机制（内置 default_config.py 共 160 个键 → PAGURE_CONFIG 指定文件覆盖）、核心 7 类参数的实测默认值与语义、可直接落地的生产配置模板，以及私有项目表单、邮件关闭激活等实测踩坑。全部默认值均在本机 Pagure 5.14.1 环境用 pagure.config 实际打印取证（2026-10-28）。安装步骤见 《Pagure 5.14.1 Ubuntu 22.04 安装指南》。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Pagure：5.14.1（源码位于 /opt/pagure，虚拟环境 /opt/pagure/venv）
• 配置文件：/etc/pagure/pagure.cfg（由 systemd 单元经 PAGURE_CONFIG 环境变量注入）
• Python：3.10.12；PostgreSQL 14.24；Redis 6.0.16；gitolite3 3.6.12-1
• 服务单元：pagure-web（Gunicorn 4 worker）、pagure-worker（Celery），均以 git 用户运行
• 验证账号：admin / q1w2e3r4

二、前置条件

• 已按安装指南完成 Pagure 5.14.1 部署并通过 Web/API/SSH 三层验证；
• 能以 root 或 git 用户在服务器执行命令；
• 理解本文的「默认值」均指 Pagure 源码 pagure/default_config.py 的内置值（未挂载任何配置文件时的生效值）。

三、参数查看与修改方式

3.1 加载机制与优先级

Pagure 的配置加载逻辑在源码 pagure/config.py 的 reload_config() 中，顺序固定：

1. 先加载内置默认：config.from_object("pagure.default_config")；
2. 若环境变量 PAGURE_CONFIG 存在，再用 config.from_envvar("PAGURE_CONFIG") 加载指定文件覆盖同名键——即配置文件里没写的键一律回落到内置默认值。

两个实测推论：

• 不设 PAGURE_CONFIG 时（无环境变量），生效的就是 default_config.py 的开发态默认值，例如 DB_URL = 'sqlite:////var/tmp/pagure_dev.sqlite'、GIT_FOLDER = '/opt/pagure/pagure/../lcl/repos'——这也是「服务重启后数据像丢了」这类问题的根源；
• PAGURE_CONFIG 指向不存在的文件时启动直接失败，实测报错：

FileNotFoundError: [Errno 2] Unable to load configuration file (No such file or directory): '/nonexistent.cfg'

3.2 查看当前生效配置

用虚拟环境解释器打印任意键的生效值（注意：systemd 单元通过 Environment= 注入了 PAGURE_CONFIG，普通 shell 里没有，查询默认值时不要带环境变量）：

/opt/pagure/venv/bin/python -c "from pagure.config import config; print(len(config.keys()), config['GIT_AUTH_BACKEND'])"

实测输出（未注入配置文件环境时的内置态）：

160 gitolite3

要点解读：默认配置共 160 个键，授权后端默认 gitolite3。查询服务器上实际生效值时，带上配置文件路径：

PAGURE_CONFIG=/etc/pagure/pagure.cfg /opt/pagure/venv/bin/python -c "from pagure.config import config; print(config['APP_URL'], config['DB_URL'])"

实测输出：

http://localhost/ postgresql://pagure:q1w2e3r4@localhost:5432/pagure

3.3 修改与生效方式

• 修改 /etc/pagure/pagure.cfg 后必须重启两个服务（配置在进程启动时加载一次）：systemctl restart pagure-web 与 systemctl restart pagure-worker（每行只操作一个单元）；
• 重启后按 3.2 的命令复核生效值；
• gitolite 相关路径（GITOLITE_*、GL_*）改动后，还需执行 pagure-admin refresh-gitolite 重新生成 ACL 配置（用法见《Pagure 5.14.1 常用 CLI 与运维命令详解》）。

四、参数总览

Pagure 5.14.1 全量 160 键按用途可分为 9 组。下表列出每组代表键与内置默认值（实测打印，长值截断展示）：

关键差异解读：默认值整体是开发态（sqlite、相对路径 lcl/、localhost.localdomain 域名），生产部署必须显式覆盖的第一梯队键是 DB_URL、GIT_FOLDER、APP_URL、SECRET_KEY 与 gitolite 五件套（GITOLITE_CONFIG/HOME/KEYDIR、GL_RC/GL_BINDIR），缺一项都会导致建仓库或 SSH 授权链路失败。

五、核心参数分类详解

5.1 站点基础参数

• APP_URL：站点对外访问地址，决定页面生成的绝对链接（邮件正文、错误提示里的跳转 URL）。默认 http://localhost.localdomain/；本环境实测设为 http://localhost/ 后 Web 首页正常返回 <title>Home - Pagure</title>（HTTP 200）。生产必改且末尾保留 /。
• SECRET_KEY：Flask 会话签名密钥。默认值仅在开发可用；生产用 python3 -c "import secrets;print(secrets.token_hex(32))" 生成并写入。更换后所有已登录会话失效（签名校验失败），属预期行为。
• ITEM_PER_PAGE：项目/工单列表每页条数，默认 48；本环境调为 50 以整除分页。
• SHORT_LENGTH：commit 与文件 hash 的短显示长度，默认 6。
• MAX_CONTENT_LENGTH：单请求体上限，默认 4194304 字节（4 MB），限制头像/附件上传大小。
• ADMIN_SESSION_LIFETIME：管理员会话有效期，内置 datetime.timedelta(seconds=1200)（20 分钟）；本环境设为 timedelta(minutes=20) 与默认等价。

5.2 数据库与队列参数

• DB_URL：SQLAlchemy 连接串。默认为开发用 sqlite；生产 postgresql://pagure:q1w2e3r4@localhost:5432/pagure（本环境实测建库后 54 张表、createdb.py 初始化成功）。口令含 @、/ 等字符时需 URL 编码。
• REDIS_HOST / REDIS_PORT / REDIS_DB：Celery broker 与事件流使用的 Redis。默认 REDIS_HOST='0.0.0.0' 值得注意——它是客户端连接地址而非监听配置，生产应指向本机回环 127.0.0.1（本环境实测值）。worker 的启动命令 celery -A pagure.lib.tasks worker 依赖该组键定位 broker。
• SESSION_COOKIE_NAME（默认 pagure）、APPLICATION_ROOT（默认 /）：会话 cookie 标识，多套 Pagure 共存同域时才需要改。

5.3 认证与账号参数

• PAGURE_AUTH：认证后端，默认 local（本地用户名密码，密码以 $2$ 前缀的 bcrypt 哈希存 users 表）。其他取值（如 fas、openid）面向 Fedora 基础设施，自托管保持 local。
• ADMIN_GROUP：拥有全站管理权限的用户组名，默认是字符串 sysadmin-main；本环境改为列表 ['pagure-admin']。注意两种类型均可被接受，与 PAGURE_ADMIN_USERS 是「组」与「硬编码用户」两条管理员通道。
• PAGURE_ADMIN_USERS：硬编码全局管理员用户名列表，默认 []。本环境实测设 ['admin'] 后，admin 账号可使用 pagure-admin 的全部子命令（admin-token list 等回显见《Pagure 5.14.1 常用 CLI 与运维命令详解》）。
• ALLOW_USER_REGISTRATION：是否开放 /user/new 注册页，默认 True。置 False 后提交注册请求会被拒绝并提示 User registration is disabled.（该行为来自源码 pagure/ui/login.py 的注册路由，属「命令+预期结果」；企业内网建实例推荐关闭、用管理脚本建号）。
• PASSWORD_SEED：密码哈希盐（默认未定义即 None）。Pagure 的 v2 密码格式（bcrypt）不依赖它，仅兼容旧版 v2 以下哈希，保持默认即可。
• CHECK_SESSION_IP：会话是否绑定 IP，默认 True。办公网出口 IP 漂移的环境建议 False，避免频繁掉线。

5.4 Git 存储与 gitolite 集成参数

这一组决定「仓库放哪、谁能推」，是 Pagure 配置的核心链路。

• GIT_FOLDER：git 仓库根目录。默认指向源码旁的 lcl/repos（开发态）；本环境实测设为 /srv/git/repositories。ENABLE_DOCS/ENABLE_TICKETS 开启时，Pagure 会自动派生 DOCS_FOLDER = GIT_FOLDER/docs、TICKETS_FOLDER = GIT_FOLDER/tickets（config.py 在加载时强制拼接，不可单独覆盖）。
• REMOTE_GIT_FOLDER：远程 PR 暂存 clone 目录，默认 lcl/remotes，生产随 GIT_FOLDER 一起迁到 /srv/git 下。
• GIT_AUTH_BACKEND：SSH 授权后端，默认 gitolite3。实测佐证：任意一次 SSH 推送的远端日志都会出现 pagure.lib.git_auth: Looking for backend: gitolite3 与 Returning helper <class 'pagure.lib.git_auth.Gitolite3Auth'>。备选 pagure、pagure_authorized_keys。
• gitolite 五件套（默认全部 None 或开发路径，生产必填，本环境实测值）：
  • GITOLITE_CONFIG = '/srv/git/gitolite-admin/conf/gitolite.conf'：Pagure 直写的 ACL 配置文件；
  • GITOLITE_HOME = '/srv/git'：gitolite 运行用户主目录（worker 生成 conf 时会设置 HOME=/srv/git）；
  • GITOLITE_KEYDIR = '/srv/git/gitolite-admin/keydir'：用户公钥落盘目录（实测 admin.pub 生成于此）；
  • GL_RC = '/srv/git/.gitolite.rc'：gitolite 运行时配置路径；
  • GL_BINDIR = '/usr/bin'：gitolite 可执行文件目录（Debian 打包版在 /usr/bin）。
• HTTP_REPO_ACCESS_GITOLITE：HTTP 协议 git 访问的网关程序路径，默认即 /usr/share/gitolite3/gitolite-shell（Debian 版实测存在）。
• SSH_COMMAND_NON_REPOSPANNER：SSH 命令模板元组，默认把 gitolite-shell <username> <cmd> <reponame> 拼进授权条目。实测 authorized_keys 中的生效条目：

command="/usr/share/gitolite3/gitolite-shell admin",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEHorpAkjE4e6NK8CBUvA6HL3NKIzf/daFhMGUIocezR admin@pagure.lab

• GITOLITE_VERSION：gitolite 大版本，默认 3，保持不动。

5.5 功能开关参数

• ENABLE_TICKETS / ENABLE_DOCS：工单与项目文档功能，默认 True；同时决定 TICKETS_FOLDER/DOCS_FOLDER 是否派生。关闭时对应子仓库不再创建。
• PRIVATE_PROJECTS：是否允许创建私有项目，默认 True。
• WEBHOOK：是否启用 WebHook 推送，默认 False；开启依赖 Redis 正常。
• EVENTSOURCE_PORT：Server-Sent 事件流端口，默认 8080；EVENTSOURCE_SOURCE 默认 None（关闭 SSE），单机部署一般两者都保持默认。
• NOGITHOOKS / HOOK_DEBUG：内置默认未定义（config.get 需显式 get 兜底）。NOGITHOOKS=True 可跳过全部 git 钩子（迁移导入仓库时用）；HOOK_DEBUG=True 会在推送时打印钩子判定过程。

5.6 邮件参数

• EMAIL_SEND：总开关，默认 False。本环境实测 False 时注册流程不发信，需手动激活（流程与实测回显见《Pagure 5.14.1 Ubuntu 22.04 安装指南》7.1 节）。
• SMTP_SERVER/SMTP_PORT/SMTP_SSL/SMTP_USERNAME/SMTP_PASSWORD：SMTP 五件套，默认 localhost:25 无认证。
• FROM_EMAIL（默认 pagure@localhost.localdomain）、DOMAIN_EMAIL_NOTIFICATIONS（默认 localhost.localdomain，决定用户邮箱别名域）、SALT_EMAIL（默认字面量 '<secret key to be changed>'，生产必改）。

5.7 会话与内部安全参数

• SESSION_COOKIE_SECURE：默认 False；站点切到 HTTPS 后必须改 True，否则 cookie 仍以明文信道发送。
• IP_ALLOWED_INTERNAL：可访问 /internal 等内部端点的来源白名单，默认 ['127.0.0.1','localhost','::1']，保持默认即可（本环境未改）。
• VIRUS_SCAN_ATTACHMENTS：附件病毒扫描，默认 False（需额外装 clamav 才有意义）。
• BLACKLISTED_GROUPS：禁止用户自建的组名，默认 ['forks','group']，实测按默认未改。

六、生产配置模板

适用场景：单机部署、4 GB 内存、NVMe/SSD 磁盘、20–50 个项目、百人以内团队，本地认证 + gitolite3 授权，邮件经内网 SMTP 中继。以下模板即本环境实测可用配置（邮件段按生产假设改写，其余为实测原值）：

# /etc/pagure/pagure.cfg — 单机生产模板（4GB 内存 / 20-50 项目）
from datetime import timedelta

ADMIN_SESSION_LIFETIME = timedelta(minutes=20)
ENABLE_TICKETS = True
ENABLE_DOCS = True
PRIVATE_PROJECTS = True

SECRET_KEY = 'pagure-lab-secret-20261028'      # 生产：token_hex(32) 重新生成
DB_URL = 'postgresql://pagure:q1w2e3r4@localhost:5432/pagure'

ADMIN_GROUP = ['pagure-admin']
PAGURE_ADMIN_USERS = ['admin']
ALLOW_USER_REGISTRATION = False                # 生产建议关闭自助注册

EMAIL_SEND = True                              # 生产接通 SMTP 后开启
EMAIL_ERROR = 'root@localhost'
SMTP_SERVER = 'smtp.internal.example.com'
SMTP_PORT = 25
SMTP_SSL = False
SMTP_USERNAME = None
SMTP_PASSWORD = None

FROM_EMAIL = 'pagure@example.com'
DOMAIN_EMAIL_NOTIFICATIONS = 'example.com'
SALT_EMAIL = 'pagure-lab-salt-20261028'        # 生产：重新生成随机串

APP_URL = 'https://pagure.example.com/'
DOC_APP_URL = None                             # 不独立部署文档子域则置 None
GIT_URL_SSH = 'ssh://git@git.example.com/'
GIT_URL_GIT = 'git://git.example.com/'

GIT_FOLDER = '/srv/git/repositories'
REMOTE_GIT_FOLDER = '/srv/git/remotes'

GITOLITE_CONFIG = '/srv/git/gitolite-admin/conf/gitolite.conf'
GITOLITE_HOME = '/srv/git'
GITOLITE_VERSION = 3
GITOLITE_KEYDIR = '/srv/git/gitolite-admin/keydir'
GL_RC = '/srv/git/.gitolite.rc'
GL_BINDIR = '/usr/bin'
GIT_AUTH_BACKEND = 'gitolite3'
HTTP_REPO_ACCESS_GITOLITE = '/usr/share/gitolite3/gitolite-shell'
SSH_COMMAND_NON_REPOSPANNER = (
    [
        "/usr/share/gitolite3/gitolite-shell",
        "%(username)s",
        "%(cmd)s",
        "%(reponame)s",
    ],
    {},
)

ITEM_PER_PAGE = 50
MAX_CONTENT_LENGTH = 4 * 1024 * 1024
SHORT_LENGTH = 6
IP_ALLOWED_INTERNAL = ['127.0.0.1', 'localhost', '::1']

EVENTSOURCE_SOURCE = None
EVENTSOURCE_PORT = 8080
WEBHOOK = False

REDIS_HOST = '127.0.0.1'
REDIS_PORT = 6379
REDIS_DB = 0

PAGURE_AUTH = 'local'
SESSION_COOKIE_SECURE = True                   # 生产 HTTPS 必改
SESSION_COOKIE_NAME = 'pagure'
CHECK_SESSION_IP = True
APPLICATION_ROOT = '/'
OLD_VIEW_COMMIT_ENABLED = False

模板要点：gitolite 五件套与 GIT_FOLDER 的路径必须互相咬合（GITOLITE_HOME 的 repositories、gitolite-admin 子目录要真实存在且归 git 用户所有）；改完配置后 systemctl restart pagure-web 与 systemctl restart pagure-worker，再用 3.2 节命令复核生效值。

七、常见问题

7.1 创建项目时「私有」复选框不受控

现象：以 API/表单创建公开项目时传 private=n，项目仍被建成私有。 原因与实测：Pagure 的项目表单用 WTForms 的 BooleanField 渲染 private 字段，而 BooleanField 对任何非空提交值（包括字符串 n）都判定为 True——只有字段整体缺席才是 False。实测创建公开项目时省略 private 字段即可。这是对接脚本时最容易踩的布尔值陷阱。

7.2 配置没生效 / 数据「消失」

排查顺序：确认进程级环境变量（systemctl show pagure-web -p Environment 应含 PAGURE_CONFIG=/etc/pagure/pagure.cfg）→ 确认文件语法（Python 语法错误会让启动直接失败）→ 重启两个服务后用 3.2 命令复核。若发现 DB_URL 是 sqlite、GIT_FOLDER 带 lcl/，说明当前进程根本没吃到配置文件，按此回查 systemd 单元的 Environment= 行。

7.3 DOC_APP_URL 配了却打不开文档站点

DOC_APP_URL 指向独立子域（如 https://docs.example.com/）时，需要单独的 DNS 解析与 Nginx server 段把该子域也反代到同一 Gunicorn 套接字，Pagure 自身不会监听子域。本环境未部署子域，直接置 None 关闭文档站点功能（ENABLE_DOCS=True 创建的 docs 仓库仍可通过 git 访问，实测 gitolite info 中可见 docs/public-demo）。

7.4 切换 HTTPS 后登录态反复丢失

站点上 HTTPS 后必须同步把 SESSION_COOKIE_SECURE 改 True，并把 APP_URL 换成 https 前缀；只改一边会出现 cookie 标记与实际协议不一致、或生成的绝对链接仍是 http 的问题。

7.5 配置文件里能写中文注释吗

可以，pagure.cfg 是标准 Python 文件（UTF-8），注释用 #。但键名与值必须是合法 Python 字面量，例如 ADMIN_SESSION_LIFETIME 需要 from datetime import timedelta 前置导入。

八、参考链接

• 配置加载源码：/opt/pagure/pagure/config.py（reload_config）；内置默认值：/opt/pagure/pagure/default_config.py
• 官方配置文档（源码内 doc/configuration.rst）：https://pagure.io/pagure/blob/master/f/doc/configuration.rst
• 配置样例文件（源码内 files/pagure.cfg.sample）：https://pagure.io/pagure/blob/master/f/files/pagure.cfg.sample
• 本文默认值取证方法：Pagure 5.14.1 + pagure.config 打印，2026-10-28 实测，共 160 键
• 延伸阅读：《Pagure 5.14.1 Ubuntu 22.04 安装指南》、《Pagure 5.14.1 常用 CLI 与运维命令详解》、《Pagure 介绍与选型指南》