亲测100%成功 如何将Nginx1.30.3打包为Flatpak

将 Nginx 1.30.3 打包为 Flatpak 100%成功 亲测

最终文件清单（位于 ~/flatpak-nginx/）

~/flatpak-nginx/├── nginx-1.30.3.tar.gz          # 源码包├── nginx.conf                   # 配置文件（所有可写路径已强制修改）├── launch.sh                    # 启动脚本（自动创建全部临时目录）└── org.nginx.nginx.json         # Flatpak 构建清单（含可选 PCRE2 模块）

0. 准备工作

0.1 安装工具

sudo apt update && sudo apt install flatpak flatpak-builder wget -y

0.2 添加 Flathub（如已添加可跳过）

flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

0.3 安装 Freedesktop SDK 24.08

flatpak install --user org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08 -y

0.4 下载 Nginx 源码并计算 SHA256

mkdir -p ~/flatpak-nginx && cd ~/flatpak-nginx

wget https://nginx.org/download/nginx-1.30.3.tar.gz

sha256sum nginx-1.30.3.tar.gz# 记录完整的十六进制哈希值

1. 编写 Nginx 配置文件（彻底解决只读问题）

文件： ~/flatpak-nginx/nginx.conf

要点： 所有日志、pid、临时目录全部强制指向沙箱内的可写路径 /var/tmp/nginx/，绝不触碰只读的 /app。

edit nginx ~/flatpak-nginx/nginx.conf

# /app/etc/nginx/nginx.conf# 【调优1】自动匹配CPU核心数，充分利用多核性能worker_processes  auto; # 【调优2】单进程可打开的最大文件数，防止高并发下报 "too many open files"worker_rlimit_nofile 65535; pid /var/tmp/nginx/nginx.pid;error_log /var/tmp/nginx/error.log info;   # 全局日志events {    # 【调优3】单进程最大连接数提升至 10240    worker_connections  10240;    # 【调优4】Linux下最优事件模型，处理万级连接无压力    use epoll;     # 【调优5】允许一次接受多个连接，提升并发接收效率    multi_accept on;}http {    include       mime.types;    default_type  application/octet-stream;    client_body_temp_path /var/tmp/nginx/client_body_temp;    proxy_temp_path       /var/tmp/nginx/proxy_temp;    fastcgi_temp_path     /var/tmp/nginx/fastcgi_temp;    uwsgi_temp_path       /var/tmp/nginx/uwsgi_temp;    scgi_temp_path        /var/tmp/nginx/scgi_temp;    # 【调优6】开启零拷贝传输，文件传输效率提升30%以上    sendfile        on;     tcp_nopush      on;    # 【调优7】长连接超时时间，减少TCP频繁握手    keepalive_timeout  65;    # 默认 server 块已注释，交由 sites/default.conf 统一管理，完美！    # server {    #    listen       8080;    #    server_name  localhost;    #    access_log  /var/tmp/nginx/access.log;    #    error_log   /var/tmp/nginx/error.log;    #    location / {    #        root   /app/share/nginx/html;    #        index  index.html index.htm;    #    }    #    error_page   500 502 503 504  /50x.html;    #    location = /50x.html {    #        root   /app/share/nginx/html;    #    }    # }}

2. 编写启动脚本（自动创建全部目录）

文件： ~/flatpak-nginx/launch.sh

要点： 启动前强制创建所有临时子目录，确保 Nginx 不会因目录缺失而报错。

edit nginx ~/flatpak-nginx/launch.sh

#!/bin/bash# 1. 定义用户专属目录USER_BASE_DIR="$HOME/.var/app/org.nginx.nginx"USER_CONF_DIR="$USER_BASE_DIR/config"USER_LOG_DIR="$USER_BASE_DIR/logs"USER_CONF_FILE="$USER_CONF_DIR/nginx.conf"USER_MIME_FILE="$USER_CONF_DIR/mime.types"# 2. 创建必要的目录结构mkdir -p "$USER_CONF_DIR/sites" "$USER_CONF_DIR/conf.d" "$USER_LOG_DIR"# 3. 首次运行：自动初始化配置文件if [ ! -f "$USER_CONF_FILE" ]; then    echo "First run: Generating default config..."    cp /app/etc/nginx/nginx.conf "$USER_CONF_FILE"    # 【关键】动态替换配置文件中的路径，避免沙箱只读报错    # 替换 mime.types 为绝对路径    sed -i "s|include       mime.types;|include       $USER_CONF_DIR/mime.types;|g" "$USER_CONF_FILE"    # 替换默认的 conf.d 路径为绝对路径    sed -i "s|include       conf.d/*.conf;|include       $USER_CONF_DIR/conf.d/*.conf;|g" "$USER_CONF_FILE"    # 将所有日志路径强制替换为用户的日志目录    sed -i "s|/var/tmp/nginx/|$USER_LOG_DIR/|g" "$USER_CONF_FILE"    # 【最佳实践】确保主配置中包含加载多网站的指令    if ! grep -q "include.*sites/*.conf" "$USER_CONF_FILE"; then        echo "Adding sites include directive..."        sed -i "/http {/a    include $USER_CONF_DIR/sites/*.conf;" "$USER_CONF_FILE"    fifi# 首次运行：复制 mime.typesif [ ! -f "$USER_MIME_FILE" ]; then    cp /app/etc/nginx/mime.types "$USER_MIME_FILE"fi# 4. 【新增】首次运行：生成默认网站配置，确保用户进来有网页可看if [ ! -f "$USER_CONF_DIR/sites/default.conf" ]; then    echo "Generating default site config..."    cat > "$USER_CONF_DIR/sites/default.conf" <<EOFserver {    listen       8080;    server_name  localhost;    access_log  $USER_LOG_DIR/default.access.log;    error_log   $USER_LOG_DIR/default.error.log;    location / {        root   /app/share/nginx/html;        index  index.html index.htm;    }    error_page   500 502 503 504  /50x.html;    location = /50x.html {        root   /app/share/nginx/html;    }}EOFfi# 5. 创建 Nginx 必须的临时目录（解决沙箱只读问题）mkdir -p /var/tmp/nginx/client_body_temp          /var/tmp/nginx/proxy_temp          /var/tmp/nginx/fastcgi_temp          /var/tmp/nginx/uwsgi_temp          /var/tmp/nginx/scgi_tempecho "Starting Nginx with config: $USER_CONF_FILE"echo "Logs directory: $USER_LOG_DIR"# 6. 启动 Nginxecho "Starting Nginx with config: $USER_CONF_FILE"echo "Logs directory: $USER_LOG_DIR"echo ""echo -e "33[32m========================================33[0m"echo -e "33[32m Nginx is running! You can visit:33[0m"echo -e "33[32m http://127.0.0.1:808033[0m"echo -e "33[32m========================================33[0m"echo ""# 启动 Nginxexec /app/sbin/nginx -c "$USER_CONF_FILE" -g "daemon off;"

赋予执行权限：chmod +x ~/flatpak-nginx/launch.sh

3. 编写 Flatpak 构建清单

文件： ~/flatpak-nginx/org.nginx.nginx.json

将 <实际SHA256> 替换为第 0.4 步获得的哈希。

edit nginx ~/flatpak-nginx/org.nginx.nginx.json

3.1 推荐清单（SDK 已含 PCRE）

{    "app-id": "org.nginx.nginx",    "runtime": "org.freedesktop.Platform",    "runtime-version": "24.08",    "sdk": "org.freedesktop.Sdk",    "command": "launch.sh",    "finish-args": ["--share=network","--filesystem=home","--share=ipc"    ],    "modules": [        {            "name": "nginx",            "buildsystem": "simple",            "build-commands": [                "./configure --prefix=/app --error-log-path=/var/tmp/nginx/error.log --http-log-path=/var/tmp/nginx/access.log --with-http_ssl_module --with-http_v2_module --with-http_realip_module --with-http_gzip_static_module",    "make -j$(nproc)",    "make install",    "install -Dm644 conf/mime.types /app/etc/nginx/mime.types",    "mkdir -p /app/share/nginx/html",    "echo '<h1>Welcome to Nginx in Flatpak!</h1><p>Edit your config in ~/.var/app/org.nginx.nginx/config/</p>' > /app/share/nginx/html/index.html"            ],            "sources": [                {                    "type": "archive",                    "path": "nginx-1.30.3.tar.gz",                    "sha256": "<实际SHA256>"                }            ]        },        {            "name": "nginx-config",            "buildsystem": "simple",            "build-commands": [                "install -Dm644 nginx.conf /app/etc/nginx/nginx.conf"            ],            "sources": [                {                    "type": "file",                    "path": "nginx.conf"                }            ]        },        {            "name": "launch-script",            "buildsystem": "simple",            "build-commands": [                "install -Dm755 launch.sh /app/bin/launch.sh"            ],            "sources": [                {                    "type": "file",                    "path": "launch.sh"                }            ]        }    ]}

3.2 备用清单（当 PCRE 缺失时使用）

如果构建时提示 the HTTP rewrite module requires the PCRE library，请将整个 org.nginx.nginx.json 替换为以下内容（同样替换 SHA256）：

{    "app-id": "org.nginx.nginx",    "runtime": "org.freedesktop.Platform",    "runtime-version": "24.08",    "sdk": "org.freedesktop.Sdk",    "command": "launch.sh",    "finish-args": [        "--share=network",        "--filesystem=home",        "--share=ipc"    ],    "modules": [        {            "name": "pcre2",            "buildsystem": "simple",            "build-commands": [                "./configure --prefix=/app",                "make -j$(nproc)",                "make install"            ],            "sources": [                {                    "type": "archive",                    "url": "https://github.com/PCRE2Project/pcre2/releases/download/pcre2-10.42/pcre2-10.42.tar.gz",                    "sha256": "b29ba4a3b7e24615b75f29de8a2c7bf0a067ce83641c6a4964e51c4c60e5d0c6"                }            ]        },        {            "name": "nginx",            "buildsystem": "simple",            "build-commands": [                "./configure --prefix=/app --error-log-path=/var/tmp/nginx/error.log --http-log-path=/var/tmp/nginx/access.log --with-http_ssl_module --with-http_v2_module --with-http_realip_module --with-http_gzip_static_module",    "make -j$(nproc)",    "make install",    "install -Dm644 conf/mime.types /app/etc/nginx/mime.types",    "mkdir -p /app/share/nginx/html",    "echo '<h1>Welcome to Nginx in Flatpak!</h1><p>Edit your config in ~/.var/app/org.nginx.nginx/config/</p>' > /app/share/nginx/html/index.html"            ],            "sources": [                {                    "type": "archive",                    "path": "nginx-1.30.3.tar.gz",                    "sha256": "<实际SHA256>"                }            ]        },        {            "name": "nginx-config",            "buildsystem": "simple",            "build-commands": [                "install -Dm644 nginx.conf /app/etc/nginx/nginx.conf"            ],            "sources": [                {                    "type": "file",                    "path": "nginx.conf"                }            ]        },        {            "name": "launch-script",            "buildsystem": "simple",            "build-commands": [                "install -Dm755 launch.sh /app/bin/launch.sh"            ],            "sources": [                {                    "type": "file",                    "path": "launch.sh"                }            ]        }    ]}

4. 构建、安装与完全清理

4.1 构建失败/重试前必须执行的完整清理

cd ~/flatpak-nginx && pkill -9 nginx 2>/dev/null || true && rm -rf build-dir && rm -rf ~/.cache/flatpak-builder/build/* && rm -rf ~/.cache/flatpak-builder/downloads/nginx-*        ~/.cache/flatpak-builder/downloads/pcre2-* && flatpak uninstall --user org.nginx.nginx -y 2>/dev/null || true && rm -rf ~/.local/share/flatpak/app/org.nginx.nginx        ~/.var/app/org.nginx.nginx

4.2 构建并安装flatpak-builder --user --install --force-clean build-dir org.nginx.nginx.json

4.3 导出离线安装包flatpak build-bundle ~/.local/share/flatpak/repo nginx.flatpak org.nginx.nginx

生成安装包的文件名是：nginx.flatpak，保存在你当前执行命令的目录下，把包发给别人

1. 别人执行安装flatpak install --user nginx.flatpak
2. 启动flatpak run org.nginx.nginx
3. 验证http://localhost:8080

查看日志（无任何权限错误）

flatpak run --command=cat org.nginx.nginx /var/tmp/nginx/access.log

flatpak run --command=cat org.nginx.nginx /var/tmp/nginx/error.log

8. 故障排除与完全卸载

• SHA256 不匹配： 重新计算并替换。
• PCRE 缺失： 使用 3.2 备用清单。
• 端口占用： sudo lsof -i :8080后 pkill -9 nginx 2>/dev/null || true

完全卸载：

flatpak uninstall --user org.nginx.nginx -y

rm -rf ~/flatpak-nginx/build-dir

rm -rf ~/.cache/flatpak-builder/build/nginx-* ~/.cache/flatpak-builder/build/pcre2-*

rm -rf ~/.cache/flatpak-builder/downloads/nginx-* ~/.cache/flatpak-builder/downloads/pcre2-*

rm -rf ~/.local/share/flatpak/app/org.nginx.nginx ~/.var/app/org.nginx.nginx

flatpak repair --user