企业官网建设流程全解析

• 应用安全
• 操作系统

Firejail 是一个基于 Linux namespaces 与 seccomp-bpf 的应用级沙箱，其核心价值在于数百个开箱即用的应用 Profile。本文围绕仓库根目录的 CONTRIBUTING.md 展开，系统讲解社区贡献者应当遵循的完整流程：从确认支持版本、规范地提交 Issue 与安全漏洞报告，到利用官方模板编写/重定向 Profile、提交 Pull Request 时的手册与语法文件更新检查清单，并延伸到桌面集成（firecfg）与 CI 自动化校验等落地细节。读完本文，你将能独立完成一次符合 Firejail 社区规范的高质量贡献，并掌握 Profile 语法、命令集合成机制与测试验证路径。

一、贡献总览：Firejail 需要什么样的贡献

Firejail 的贡献入口非常明确：CONTRIBUTING.md 欢迎三类工作：提交 Issue（提问、提供信息、请求新 Profile 或新特性、报告疑似 Bug）、报告安全漏洞、提交 Pull Request（增强、Bugfix 或新 Profile）。无论是哪一类，都有一个共同前提：先确认你使用的版本仍在支持范围内。

1.1 先确认版本受支持再发言

CONTRIBUTING.md 明确要求：在评论 Issue/Discussion/PR 或新开 Issue 之前，确保自己使用的是受支持的版本。SECURITY.md 给出了精确的版本政策：

• 除非另有说明，项目只支持最新发布版和当前开发版；
• 旧版本通常带有过时的 Profile，且可能包含已在后续版本修复的 Bug 与安全漏洞；
• 检查命令：终端执行firejail --version；
• 如果你的发行版自带版本落后于最新版（且发布已过去数日），应联系发行版维护者请求更新软件包；临时方案是按 README.md 的 Building 章节 从源码构建当前开发版。

SECURITY.md 中还附有一张历史版本支持表，例如 0.9.80 由项目官方支持，0.9.72 虽已停止官方支持但仍由 Debian 12、Ubuntu 24.04 LTS 等发行版维护，0.9.66 由 Ubuntu 22.04 LTS 维护——这张表说明“官方支持”与“发行版维护”是两条不同的线，贡献时以官方支持版本为讨论基准。

二、规范地提交 Issue：Bug 报告应该附上哪些信息

CONTRIBUTING.md 对 Bug 报告给出了最小信息集，这些信息直接决定了维护者能否快速复现与定位：

1. firejail 版本：不确定时执行firejail --version；
2. Linux 发行版：便于必要时复现问题；
3. 回归信息：如果确认问题在更早版本中不存在，务必说明，这能极大缩小排查范围；
4. --noprofile对照实验：报告“某程序在 firejail 下无法运行”时，请同时运行firejail --noprofile firefox并反馈是否正常。这是关键的分流手段——--noprofile会跳过 Profile 加载，若加上 Profile 才失败、去掉就成功，问题基本锁定在 Profile 而非沙箱核心；
5. 逐步禁用 Profile 选项：尝试编辑/etc/firejail/<ProgramName.profile>，逐个禁用可疑配置项直到定位出元凶，这会显著加快问题解决。

2.1 请求新 Profile：走专用 Issue 通道

如果只是想请求一个仓库尚未收录的程序 Profile，CONTRIBUTING.md 指向了一个专门的集中式 Issue（Profile requests，编号 1139），在其下添加评论即可，避免重复开 Issue 淹没维护者的视野。仓库现有 Profile 规模庞大，分布在 etc/profile-a-l 与 etc/profile-m-z 两个目录（数百个.profile文件），先在此处检索确认确实没有你要的程序再提交请求。

2.2 常见坑：Debian 系务必同时安装 firejail-profiles

CONTRIBUTING.md 特别提醒：在 Debian、Ubuntu、Linux Mint 及相关发行版上从软件源安装时，必须确保firejail与firejail-profiles两个包都装上了。未安装 firejail-profiles 是 Issue 的常见来源——因为系统 Profile（如 etc/profile-a-l/、etc/profile-m-z/ 下的全部.profile）正是由该包提供的。这与 README.md 中 Ubuntu PPA 安装命令sudo apt-get install firejail firejail-profiles的写法相互印证。

三、报告安全漏洞：专用渠道与边界

安全漏洞不走普通 Issue，CONTRIBUTING.md 将其单独指向 SECURITY.md，后者给出了唯一的报告邮箱：netblue30@protonmail.com。SECURITY.md 同时强调“我们非常严肃地对待安全 Bug”，因此贡献者不应在公开渠道贴出可利用的漏洞细节，而应先走私有报告通道，等待维护者处理后再公开讨论。

四、编写新 Profile：官方模板是唯一推荐的起点

Pull Request 中数量最大的类型就是新 Profile，CONTRIBUTING.md 明确指出“编写新 Profile 最简便的方式是使用 Profile 模板”——即 etc/templates/profile.template。模板开头的## --- CUT HERE ---标记意味着：该标记以上的行是模板自身的说明文档，不要复制进 Profile；标记以下才是要复制的内容骨架。

4.1 模板头部：注释规范与信息头

模板对被复制进 Profile 的内容给出了严格的注释语法约定：

• ##开头的行是模板说明注释，不应复制进 Profile；
• #开头的行属于某个段落的注释，应随该段一起复制（例如# Allow系列注释）；
• #（无空格）开头的行在 Profile 中很常见；
• ##（无空格）开头的行仅在特殊情况下才复制。

每个新 Profile 都以这样的信息头开始：

# Firejail profile for PROGRAM_NAME # Description: DESCRIPTION OF THE PROGRAM # This file is overwritten after every install/update ##quiet # Persistent local customizations include PROFILE.local # Persistent global definitions include globals.local

其中include PROFILE.local让用户可以在 Profile 被更新覆盖后仍保留本地定制，include globals.local引入全局持久定义。模板还提醒：通常会把程序专属配置目录（如${HOME}/PROGRAMNAME或${HOME}/.config/PROGRAMNAME）加入 etc/inc/disable-programs.inc（保持列表有序），再在 Profile 中通过noblacklist取消黑名单。

4.2 段落结构：Profile 的标准骨架

模板明确规定了 Profile 的段落结构与顺序，各段之间用单个空行分隔，段内条目按字母序排列：

HEADER（信息头） COMMENTS（注释） IGNORES（ignore 命令） NOBLACKLISTS（noblacklist 反黑名单） ALLOW INCLUDES（allow-*.inc 白名单式 include） BLACKLISTS（blacklist 黑名单） DISABLE INCLUDES（disable-*.inc 严格化 include） NOWHITELISTS（nowhitelist） MKDIRS（mkdir/mkfile） WHITELISTS（whitelist） WHITELIST INCLUDES（whitelist-*.inc） OPTIONS（caps*、net*、no*、protocol、seccomp*） PRIVATE OPTIONS（disable-mnt、private-*、writable-*） DBUS FILTER（dbus-user / dbus-system） SPECIAL OPTIONS（mdwx、noexec、read-only、join-or-start） REDIRECT INCLUDES（重定向 include）

这是维护者审查 PR 时的硬性预期结构，偏离它会导致 Profile 被要求重排。模板中给出了大量可直接取用的指令示例，例如网络与系统调用限制：

#net none #netfilter #protocol unix,inet,inet6,netlink,packet,bluetooth #seccomp ##seccomp !chroot #seccomp.block-secondary #apparmor #caps.drop all

以及私密性选项与 DBus 过滤：

#disable-mnt ##private #private-bin PROGRAMS #private-cache #private-dev #private-etc FILES #private-tmp #dbus-user filter #dbus-user.own com.github.netblue30.firejail #dbus-user.talk ca.desrt.dconf #dbus-user.talk org.freedesktop.Notifications #dbus-system none

4.3 路径宏：${CFG}、${HOME} 等占位符

模板允许在路径中使用宏来替代常见位置：

模板提示可查看~/.config/user-dirs.dirs了解这些宏如何映射到实际路径。宏的底层实现与完整列表可在 src/firejail/macros.c 中确认，且 Makefile 会从该源码自动抽取${...}形式的宏生成contrib/syntax/lists/profile_macros.list，用于后续语法高亮文件的合成。

4.4 private-etc 的官方参数模板

模板对private-etc给出了非常实用的分类取值建议：

• Common：alternatives,ld.so.cache,ld.so.conf,ld.so.conf.d,ld.so.preload,locale,locale.alias,locale.conf,localtime,mime.types,xdg（Extra：group,magic,magic.mgc,passwd）；
• 3D：bumblebee,drirc,glvnd,nvidia；Audio：alsa,asound.conf,machine-id,pulse；D-Bus：dbus-1,machine-id；GUI：fonts,pango,X11；GTK：dconf,gconf,gtk-2.0,gtk-3.0；KDE：kde4rc,kde5rc；
• Networking：ca-certificates,crypto-policies,host.conf,hostname,hosts,nsswitch.conf,pki,protocols,resolv.conf,rpc,services,ssl（Extra：gai.conf,proxychains.conf）；Qt：Trolltech.conf。

模板还特别警告：private-opt会把整个路径复制进内存，可能触发 firejail.config 中的file-copy-limit，因此新 Profile 建议用whitelist /opt/NAME代替private-opt NAME。这些约定不是空话——CI 中有专门脚本强制其正确性：ci/check/profiles/private-etc-always-required.sh 会逐一检查每个使用了private-etc的 Profile 是否包含alternatives、ld.so.cache、ld.so.preload这三个必需项，缺失即报错。

4.5 编写技巧：如何摸清程序到底用了哪些文件

模板给出了一套非常实用的“行为探测”流程，用于决定 blacklist/whitelist 的内容：

1. 用命名沙箱启动程序并忽略private-bin：firejail --name=test --ignore=private-bin [--profile=PROFILE] --private BINARY；
2. 正常使用程序：做配置修改并保存、打开新文档、安装插件等；
3. 加入沙箱查看变更：firejail --join=test bash；
4. 用ls -aR观察哪些文件发生了变化，据此填充 blacklist 与 whitelist 段落。

4.6 弱化 Profile：noprofile.profile 的兜底定位

如果程序在最强 Profile 下依然无法工作，仓库还提供了一个“最弱 Profile”作为诊断兜底：etc/profile-m-z/noprofile.profile。它由noblacklist /sys/fs、noblacklist /sys/module、nowhitelist /sys/module/nvidia*、allow-debuggers、allusers、keep-config-pulse、keep-fd all、keep-var-tmp、writable-etc、writable-var等“放宽”指令组成。文件头明确说明：若程序连它都无法运行，则基本可以断定与 firejail 不兼容。同时它也提醒，即便使用该 Profile，仍有少量行为不可避免：部分环境变量会被清除、firejail.config 中的force-nonewprivs yes之类选项仍会生效、会创建私有 PID namespace、且存在一段最小化的硬编码黑名单。这与 CONTRIBUTING.md 中“用--noprofile做对照实验”的建议互为补充：前者是命令行级跳过 Profile，后者是 Profile 级的最小化约束。

五、重定向 Profile：一劳永逸的别名方案

CONTRIBUTING.md 要求已写好的 Profile 必须遵循模板规则，而模板体系其实包含两个：etc/templates/profile.template 用于常规 Profile，etc/templates/redirect_alias-profile.template 用于“别名/重定向”Profile。后者解决的核心场景是：多个程序共用同一份沙箱配置（典型如 LibreOffice 全家桶）。其结构是信息头加一行关键指令：

# Firejail profile for PROGRAM_NAME # Description: DESCRIPTION include PROFILE.profile

即把PROFILE.profile整体拉进来，同时可通过##ignore net none、##ignore private-bin、##ignore seccomp等ignore指令选择性忽略被 include 进来的某个选项。模板特别提示：只有重定向到*-common.profile时才取消注释include globals.local；当private被设置时绝不能在重定向 Profile 里使用mkdir/mkfile（见 Issue #903）。firejail-profile(5) 手册 中同样记录了这种 alias/redirect 用法，与模板相互印证。

六、新增命令的 Checklist：四件必须同步更新的事

CONTRIBUTING.md 对“新增 Profile 命令”给出了硬性检查清单，这是很多初次贡献者容易遗漏的部分：

• 更新手册页：firejail(1)（src/man/firejail.1.in）与firejail-profile(5)（src/man/firejail-profile.5.in）；
• 更新 shell 补全：bash 与 zsh 两个目录（src/bash_completion、src/zsh_completion）；
• 更新语法文件：运行make syntax或直接make；
• 更新--help（src/firejail/usage.c）。

其中“更新语法文件”看似神秘，实际上语法文件是自动生成的。Makefile 展示了完整的生成链路：

• contrib/syntax/lists/profile_commands_arg0.list与arg1.list：从 src/firejail/profile.c 中正则抽取strcmp(ptr, "...")形式的命令字符串自动生成；
• contrib/syntax/lists/profile_conditionals.list：从profile.c的Cond conditionals[]数组抽取；
• contrib/syntax/lists/profile_macros.list：从 src/firejail/macros.c 抽取${...}宏；
• syscall_groups.list从 src/lib/syscall.c 抽取，syscalls.list从 src/include/syscall*.h 抽取，system_errnos.list从 src/lib/errno.c 抽取；
• 随后edit_syntax_file把上述列表注入contrib/syntax/files/*.in模板，生成 Vim 语法文件 contrib/syntax/files/firejail.vim、GtkSourceView 语言定义 contrib/syntax/files/firejail-profile.lang 与示例文件 contrib/syntax/files/example。

这就是为什么新增命令后“跑一遍make syntax”即可让编辑器高亮跟上——你写的 Profile 语法本身就来自源码。Vim 侧还配套了 contrib/vim/ftdetect/firejail.vim 与 contrib/vim/ftplugin/firejail.vim 完成文件类型探测，安装时由 Makefile 统一部署。

七、Profile 语法速览：评论、条件与 include

理解模板语法有助于阅读与审查 Profile，firejail-profile(5) 手册 对此有权威描述，与模板中的用法一一对应：

• 注释：# this is a comment，例如net none # this command creates an empty network namespace；
• 条件行：?CONDITIONAL: profile line，例如?HAS_APPIMAGE: whitelist ${HOME}/special/appimage/dir——仅当命令行指定了--appimage时才加载该行。目前支持的条件包括HAS_APPIMAGE、HAS_NET、HAS_NODBUS、HAS_NOSOUND、HAS_PRIVATE、HAS_X11，以及可在 firejail.config 中全局启用的ALLOW_TRAY、BROWSER_DISABLE_U2F、BROWSER_ALLOW_DRM。条件行后的 Profile 行可以是任何指令，唯独不能是quiet与include；
• include：include other.profile，例如include /etc/firejail/disable-common.inc，路径可带${HOME}、${CFG}等宏前缀；${CFG}通常展开为/etc/firejail或/usr/local/etc/firejail；
• 空格路径：包含空格的文件/目录名无需转义，如blacklist ~/My Virtual Machines。

仓库测试目录 test/profiles 提供了大量对应的行为测试，例如cond1.profile（内容仅?HAS_NODBUS: private）配合 profile_conditional.exp 验证条件解析；ignore.profile（private、seccomp、name test）配合 profile_ignore.exp 验证ignore指令；profile_build.exp用firejail --build=/tmp/firejailtest.profile /usr/bin/true验证 Profile 自动构建。整套测试由 test/profiles/profiles.sh 驱动，涵盖 comments、recursivity、appname、syntax、read-only、no-permissions、multiple profiles、noprofile 等场景，并会针对 audacity、chromium-browser、firefox、gimp、vlc 等真实程序执行端到端验证。

八、桌面集成：firecfg 与 firecfg.config 的角色

CONTRIBUTING.md 虽未展开，但新 Profile 提交后通常要进入 firecfg 的自动化集成，这是让 Profile 真正生效的关键一步。firecfg.config 是 firecfg 工具的程序清单，按字母序维护（全文件 1083 行，覆盖 0ad、Telegram、firefox、libreoffice 直至 zulip 等数百个程序）。firecfg 会为清单中的程序在/usr/local/bin建立指向 firejail 的符号链接，使桌面环境启动程序时自动进入沙箱。

CONTRIBUTING.md 与模板均要求“把程序名加入 src/firecfg/firecfg.config（保持列表有序）”，但模板同时给出两条重要告诫：

1. 不要为关键系统工具添加，否则可能破坏操作系统（相关讨论见 Issue #2507），例如ar、atool、zpaq、zstd*等 CLI 归档工具在 firecfg.config 中被注释禁用，原因是会干扰 Arch 上 makepkg 的打包流程（见 Issue #3095）；
2. 默认不集成文本编辑器（如#atom、#atom-beta被注释），因为把编辑器套进沙箱可能阻止用户修改~/.config与/etc下的某些配置（见 Issue #6002），该策略写在 firecfg.config 开头的 Note2 中。

CI 对这份清单有自动校验：ci/check/profiles/sort-firecfg.config.sh 用sed剥离注释后用LC_ALL=C sort -c -u检查列表是否有序且无重复；ci/check/profiles/sort-disable-programs.sh 对 etc/inc/disable-programs.inc 做同样的排序与去重校验。因此贡献者只需“保持列表有序”，其余交给 CI。

九、提交 PR 前的自检清单

综合 CONTRIBUTING.md 与仓库配套约束，提交 Pull Request 前建议逐项核对：

1. 版本前提：基于受支持的版本/开发分支工作；
2. Profile 质量：从 etc/templates/profile.template 起步，段落结构完整、段内按字母序、单空行分隔；重定向场景使用 etc/templates/redirect_alias-profile.template；
3. 测试充分：模板要求“根据程序复杂度投入充足时间测试”，覆盖配置保存、文档打开、插件安装等关键路径；参考 test/profiles 的测试模式；
4. 新增命令四件套：手册（firejail(1)/firejail-profile(5)）、shell 补全、语法文件（make syntax）、--help；
5. 集成登记：把程序名按字母序加入 src/firecfg/firecfg.config，并注意排除关键系统工具与文本编辑器；
6. CI 绿灯：确保 ci/check 下的排序、去重与 private-etc 必需项检查全部通过。

十、进一步深入：wiki 与手册资源

CONTRIBUTING.md 鼓励贡献者把使用技巧沉淀到项目 wiki。若想更深地理解 Profile 体系，仓库内最权威的参考是 src/man/firejail-profile.5.in（Profile 语法与构建手册，含模板位置、Scripting 规则、条件与 include 的完整语义）与 src/man/firejail.1.in（主命令手册，涵盖--profile、--noprofile、--build等选项）。--build模式值得一提：firejail --build=appname.profile appname会运行程序并自动抽取出一个白名单式 Profile 保存到当前目录，之后仍需人工在文本编辑器中增删沙箱选项并反复测试，最终复制到~/.config/firejail并执行sudo firecfg完成桌面集成——这与模板手工路线互为补充，是快速起步的另一条路径。

• 应用安全
• 操作系统