{
    // ✓ 正确：反向域名格式，全部小写
    "app-id": "com.example.MyApp",
    
    // ✗ 错误：大写字母
    "app-id": "com.example.myApp",
    
    // ✗ 错误：没有使用自己的域名
    "app-id": "org.gnome.MyApp",
    
    // ✗ 错误：过于简短
    "app-id": "myapp"
}

{
    // ✓ 推荐：使用最新稳定版
    "runtime-version": "24.08",  // Freedesktop
    "runtime-version": "47",     // GNOME
    "runtime-version": "6.8",    // KDE

    // ✗ 避免：使用已停止维护的旧版本
    "runtime-version": "20.08",  // 已停止安全更新
    "runtime-version": "1.6"     // 太旧
}

{
    "finish-args": [
        // ✓ 推荐：精确指定需要的权限
        "--socket=wayland",
        "--socket=fallback-x11",
        "--share=ipc",
        "--filesystem=xdg-download",
        "--talk-name=org.freedesktop.Notifications",
        
        // ✗ 避免：过度权限
        "--filesystem=host",        // 过于宽泛
        "--filesystem=home",        // 过于宽泛
        "--device=all",             // 过于宽泛
        "--share=network",          // 如果不需要网络
        "--talk-name=*"             // 禁止
    ]
}

{
    "sources": [
        {
            "type": "git",
            "url": "https://github.com/example/myapp.git",
            "tag": "v1.0.0",
            "commit": "abc123def456789..."  // ✓ 推荐：同时指定 commit
            
            // ✗ 避免：只指定 branch（Flathub 禁止）
            // "branch": "main"
        }
    ]
}

{
    "modules": [
        {
            "name": "python-deps",
            "buildsystem": "simple",
            "build-commands": [
                // ✓ 使用 --no-index 进行离线安装
                "pip3 install --no-index --find-links=\"file://${PWD}\" --prefix=${FLATPAK_DEST} requests"
            ],
            "sources": [
                // ✓ 预先声明所有依赖
                {"type": "file", "url": "https://.../requests-2.31.0-py3-none-any.whl", "sha256": "..."},
                {"type": "file", "url": "https://.../urllib3-2.0.7-py3-none-any.whl", "sha256": "..."}
            ]
        }
    ]
}

# 启用 ccache 加速 C/C++ 编译
flatpak-builder --ccache --force-clean --repo=repo builddir app.json

# 在 Manifest 中配置 ccache
{
    "build-options": {
        "env": {
            "CCACHE_DIR": "/run/ccache"
        },
        "build-args": ["--filesystem=host"]
    }
}

# 增量构建（只重新编译修改过的模块）
flatpak-builder --repo=repo builddir app.json

# 强制重建特定模块
rm -rf builddir/.flatpak-builder/build/myapp
flatpak-builder --repo=repo builddir app.json

# 查看构建日志
ls builddir/logs/

# 保存构建日志
flatpak-builder --repo=repo builddir app.json 2>&1 | tee build.log

# 只保存错误日志
flatpak-builder --repo=repo builddir app.json 2>&1 | grep -E "(error|Error|ERROR)" | tee errors.log

<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
    <id>com.example.MyApp</id>
    <name>My Application</name>
    <!-- 简短摘要，不超过 35 个字符 -->
    <summary>A powerful tool for doing amazing things</summary>
    
    <metadata_license>CC0-1.0</metadata_license>
    <project_license>GPL-3.0-or-later</project_license>
    
    <!-- 详细描述 -->
    <description>
        <p>
            第一段：简要说明应用做什么、为谁设计。
        </p>
        <p>主要功能：</p>
        <ul>
            <li>功能一：详细描述</li>
            <li>功能二：详细描述</li>
            <li>功能三：详细描述</li>
        </ul>
        <p>
            其他说明：特殊要求、已知限制等。
        </p>
    </description>
    
    <!-- 关键词，用于搜索 -->
    <keywords>
        <keyword>keyword1</keyword>
        <keyword>keyword2</keyword>
        <keyword>keyword3</keyword>
    </keywords>
    
    <url type="homepage">https://example.com/myapp</url>
    <url type="bugtracker">https://github.com/example/myapp/issues</url>
    <url type="vcs-browser">https://github.com/example/myapp</url>
    <url type="translate">https://hosted.weblate.org/projects/myapp/</url>
    <url type="help">https://example.com/myapp/docs</url>
    
    <developer id="com.example">
        <name>Example Developer</name>
    </developer>
    
    <branding>
        <color type="primary" scheme_preference="light">#4a90d9</color>
        <color type="primary" scheme_preference="dark">#1a5fb4</color>
    </branding>
    
    <content_rating type="oars-1.1" />
    
    <releases>
        <release version="1.2.0" date="2026-05-01">
            <description>
                <p>新版本更新内容：</p>
                <ul>
                    <li>新增功能 A</li>
                    <li>修复 Bug B</li>
                    <li>性能优化 C</li>
                </ul>
            </description>
        </release>
        <release version="1.1.0" date="2026-03-15">
            <description>
                <p>上一版本更新内容。</p>
            </description>
        </release>
        <release version="1.0.0" date="2026-01-01">
            <description>
                <p>首次发布。</p>
            </description>
        </release>
    </releases>
    
    <recommends>
        <control>pointing</control>
        <control>keyboard</control>
        <control>touch</control>
    </recommends>
    
    <requires>
        <display_length compare="ge">360</display_length>
    </requires>
    
    <supports>
        <display_length compare="ge">768</display_length>
    </supports>
</component>

# com.example.MyApp.desktop
[Desktop Entry]
# 基本信息
Type=Application
Name=My Application
GenericName=Text Editor
Comment=A powerful tool for doing amazing things

# 启动配置
Exec=myapp %U
Icon=com.example.MyApp
StartupNotify=true
StartupWMClass=com-example-MyApp

# 分类（至少选择一个主分类）
Categories=Utility;TextEditor;Development;
Keywords=text;editor;code;

# 文件关联
MimeType=text/plain;text/x-python;text/x-csrc;

# D-Bus 激活
DBusActivatable=true

# 无障碍
X-GNOME-UsesNotifications=true

#!/bin/bash
# update-version.sh - 更新 Flatpak 应用版本

APP_ID="com.example.MyApp"
NEW_VERSION="$1"
OLD_VERSION="$2"

echo "=== 更新 $APP_ID: $OLD_VERSION → $NEW_VERSION ==="

# 1. 更新 Manifest 中的 Git tag 和 commit
MANIFEST="${APP_ID}.json"
OLD_TAG="v${OLD_VERSION}"
NEW_TAG="v${NEW_VERSION}"

# 获取新版本的 commit hash
NEW_COMMIT=$(git ls-remote https://github.com/example/myapp.git "refs/tags/${NEW_TAG}" | awk '{print $1}')
echo "新版本 commit: $NEW_COMMIT"

# 2. 更新 Manifest
jq --arg tag "$NEW_TAG" --arg commit "$NEW_COMMIT" \
    '.modules[0].sources[0].tag = $tag | .modules[0].sources[0].commit = $commit' \
    "$MANIFEST" > "${MANIFEST}.tmp" && mv "${MANIFEST}.tmp" "$MANIFEST"

# 3. 更新 AppStream 元数据
# 在 metainfo.xml 中添加新的 release 条目

# 4. 测试构建
flatpak-builder --force-clean --repo=repo builddir "$MANIFEST"

# 5. 测试安装
flatpak install -y repo "$APP_ID"

# 6. 提交更改
git add "$MANIFEST" "*.metainfo.xml"
git commit -m "Update to v${NEW_VERSION}"

echo "=== 更新完成，请推送到 Flathub ==="

#!/bin/bash
# upgrade-runtime.sh - 升级 Flatpak 运行时版本

APP_ID="com.example.MyApp"
OLD_RUNTIME_VERSION="46"
NEW_RUNTIME_VERSION="47"

echo "=== 升级运行时: $OLD_RUNTIME_VERSION → $NEW_RUNTIME_VERSION ==="

MANIFEST="${APP_ID}.json"

# 1. 更新 Manifest 中的运行时版本
jq --arg ver "$NEW_RUNTIME_VERSION" \
    '."runtime-version" = $ver' \
    "$MANIFEST" > "${MANIFEST}.tmp" && mv "${MANIFEST}.tmp" "$MANIFEST"

# 2. 安装新版本 SDK
flatpak install -y flathub org.gnome.Sdk//${NEW_RUNTIME_VERSION} org.gnome.Platform//${NEW_RUNTIME_VERSION}

# 3. 测试构建
flatpak-builder --force-clean --repo=repo builddir "$MANIFEST"

# 4. 运行测试
flatpak install -y repo "$APP_ID"
flatpak run "$APP_ID" --version

# 5. 检查弃用警告
echo "检查是否有弃用 API 警告..."
flatpak-builder --force-clean --repo=repo builddir "$MANIFEST" 2>&1 | grep -i "deprecat"

echo "=== 运行时升级完成 ==="

#!/bin/bash
# update-dependencies.sh - 检查并更新依赖

MANIFEST="com.example.App.json"

echo "=== 依赖更新检查 ==="

# 检查每个 git 源的最新 tag
jq -r '.modules[] | .sources[]? | select(.type == "git") | "\(.url) \(.tag)"' "$MANIFEST" | \
while read url tag; do
    echo ""
    echo "仓库: $url"
    echo "当前: $tag"
    
    # 获取最新 tag
    LATEST=$(git ls-remote --tags "$url" 2>/dev/null | \
        grep -v '\^{}' | \
        sort -t/ -k3 -V | \
        tail -1 | \
        sed 's|.*refs/tags/||')
    
    if [ -n "$LATEST" ] && [ "$LATEST" != "$tag" ]; then
        echo "最新: $LATEST ← 需要更新！"
    else
        echo "已是最新"
    fi
done

{
    "app-id": "com.example.SecureApp",
    "runtime": "org.freedesktop.Platform",
    "runtime-version": "24.08",
    "sdk": "org.freedesktop.Sdk",
    "command": "secure-app",
    
    "finish-args": [
        "--socket=wayland",
        "--socket=fallback-x11",
        "--share=ipc",
        "--filesystem=xdg-download",
        "--talk-name=org.freedesktop.Notifications"
    ],
    
    "build-options": {
        "cflags": "-O2 -fstack-protector-strong -D_FORTIFY_SOURCE=2",
        "cxxflags": "-O2 -fstack-protector-strong -D_FORTIFY_SOURCE=2",
        "ldflags": "-Wl,-z,relro,-z,now"
    },
    
    "modules": [
        {
            "name": "secure-app",
            "buildsystem": "meson",
            "config-opts": [
                "-Dbuildtype=release",
                "-Dhardening=true"
            ],
            "sources": [
                {
                    "type": "git",
                    "url": "https://github.com/example/secure-app.git",
                    "tag": "v1.0.0",
                    "commit": "abc123..."
                }
            ]
        }
    ]
}

#!/bin/bash
# security-audit.sh - Flatpak 安全自动审计

APP_ID="$1"
MANIFEST="${APP_ID}.json"
REPORT="/tmp/flatpak-security-audit.txt"

echo "=== Flatpak 安全审计报告 ===" > "$REPORT"
echo "应用: $APP_ID" >> "$REPORT"
echo "时间: $(date)" >> "$REPORT"
echo "" >> "$REPORT"

# 1. 检查危险权限
echo "--- 权限检查 ---" >> "$REPORT"
FINISH_ARGS=$(jq -r '."finish-args"[]' "$MANIFEST")

check_permission() {
    local perm="$1"
    local risk="$2"
    local desc="$3"
    
    if echo "$FINISH_ARGS" | grep -q "$perm"; then
        echo "[$risk] $desc: $perm" >> "$REPORT"
    fi
}

check_permission "filesystem=host" "🔴 极高" "完整文件系统访问"
check_permission "filesystem=home" "🔴 高" "主目录访问"
check_permission "device=all" "🔴 高" "所有设备访问"
check_permission "talk-name=*" "🔴 极高" "所有 D-Bus 服务访问"
check_permission "system-talk-name=" "🟡 中" "系统 D-Bus 访问"
check_permission "share=network" "🟢 低" "网络访问"
check_permission "socket=x11" "🟡 中" "X11 访问（截屏风险）"

# 2. 检查源代码安全
echo "" >> "$REPORT"
echo "--- 源代码检查 ---" >> "$REPORT"

# 检查是否有 branch（应使用 tag+commit）
BRANCH_COUNT=$(jq '[.modules[] | .sources[]? | select(.type == "git" and .branch)] | length' "$MANIFEST")
if [ "$BRANCH_COUNT" -gt 0 ]; then
    echo "[警告] 发现 $BRANCH_COUNT 个使用 branch 的 Git 源" >> "$REPORT"
fi

# 检查 SHA256
TOTAL_SOURCES=$(jq '[.modules[] | .sources[]? | select(.type != "git")] | length' "$MANIFEST")
HASHED_SOURCES=$(jq '[.modules[] | .sources[]? | select(.type != "git" and .sha256)] | length' "$MANIFEST")
echo "远程源: $TOTAL_SOURCES, 有校验和: $HASHED_SOURCES" >> "$REPORT"

# 3. 输出报告
cat "$REPORT"
echo ""
echo "报告已保存到: $REPORT"

#!/bin/bash
# check-updates.sh - 检查 Flatpak 应用更新

echo "=== Flatpak 更新检查 ==="
echo ""

# 检查运行时更新
echo "--- 运行时更新 ---"
flatpak update --appstream 2>/dev/null
RUNTIME_UPDATES=$(flatpak remote-ls --runtime --updates 2>/dev/null | wc -l)
echo "可更新的运行时: $RUNTIME_UPDATES"

# 检查应用更新
echo ""
echo "--- 应用更新 ---"
APP_UPDATES=$(flatpak remote-ls --app --updates 2>/dev/null | wc -l)
echo "可更新的应用: $APP_UPDATES"

if [ "$RUNTIME_UPDATES" -gt 0 ] || [ "$APP_UPDATES" -gt 0 ]; then
    echo ""
    echo "可用更新:"
    flatpak remote-ls --updates 2>/dev/null
    
    read -p "是否更新？(y/n) " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        flatpak update -y
    fi
else
    echo ""
    echo "所有应用和运行时已是最新版本。"
fi

#!/bin/bash
# maintenance.sh - Flatpak 定期维护

echo "=== Flatpak 定期维护 ==="
echo "时间: $(date)"
echo ""

# 1. 更新应用元数据
echo "1. 更新应用元数据..."
flatpak update --appstream -y --noninteractive 2>/dev/null

# 2. 清理未使用的运行时
echo "2. 清理未使用的运行时..."
UNUSED=$(flatpak unused 2>/dev/null | wc -l)
echo "   未使用的运行时/扩展: $UNUSED"
if [ "$UNUSED" -gt 0 ]; then
    flatpak uninstall --unused -y --noninteractive 2>/dev/null
    echo "   已清理"
fi

# 3. 修复损坏的安装
echo "3. 检查并修复安装..."
flatpak repair 2>/dev/null || echo "   修复完成"

# 4. 磁盘空间报告
echo "4. 磁盘空间报告..."
echo "   用户级: $(du -sh ~/.local/share/flatpak/ 2>/dev/null | cut -f1)"
echo "   系统级: $(du -sh /var/lib/flatpak/ 2>/dev/null | cut -f1)"

echo ""
echo "=== 维护完成 ==="

# ~/.config/systemd/user/flatpak-maintenance.service
[Unit]
Description=Flatpak Maintenance

[Service]
Type=oneshot
ExecStart=/usr/local/bin/flatpak-maintenance.sh

# ~/.config/systemd/user/flatpak-maintenance.timer
[Unit]
Description=Run Flatpak maintenance weekly

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target

# 启用定时维护
systemctl --user daemon-reload
systemctl --user enable --now flatpak-maintenance.timer

# 查看定时器状态
systemctl --user list-timers flatpak-maintenance.timer

#!/bin/bash
# enterprise-lifecycle.sh - 企业 Flatpak 应用生命周期管理

ACTION="$1"
APP_ID="$2"

case "$ACTION" in
    deploy)
        echo "部署应用: $APP_ID"
        flatpak install -y internal-repo "$APP_ID"
        flatpak override --user --filesystem=~/corporate-data "$APP_ID"
        echo "✓ 部署完成"
        ;;
    update)
        echo "更新应用: $APP_ID"
        flatpak update -y "$APP_ID"
        echo "✓ 更新完成"
        ;;
    audit)
        echo "审计应用: $APP_ID"
        flatpak info --show-permissions "$APP_ID"
        flatpak info --show-metadata "$APP_ID"
        echo "✓ 审计完成"
        ;;
    retire)
        echo "退役应用: $APP_ID"
        flatpak uninstall -y "$APP_ID"
        rm -rf ~/.var/app/"$APP_ID"
        echo "✓ 退役完成"
        ;;
    *)
        echo "用法: $0 {deploy|update|audit|retire} APP_ID"
        exit 1
        ;;
esac

#!/bin/bash
# post-release-monitor.sh - 发布后监控

APP_ID="$1"
VERSION="$2"

echo "=== 发布后监控: $APP_ID v$VERSION ==="

# 1. 检查 Flathub 上的状态
echo "1. 检查 Flathub 状态..."
if flatpak remote-info flathub "$APP_ID" &>/dev/null; then
    echo "   ✓ 应用已在 Flathub 上发布"
    flatpak remote-info flathub "$APP_ID" | grep -E "Version|Branch"
else
    echo "   ⏳ 应用正在审核中"
fi

# 2. 检查用户反馈
echo ""
echo "2. 用户反馈检查..."
echo "   请访问: https://github.com/flathub/${APP_ID}/issues"
echo "   请访问: https://flathub.org/apps/${APP_ID}"

# 3. 检查安全更新
echo ""
echo "3. 安全检查..."
echo "   运行时版本: $(jq -r '."runtime-version"' ${APP_ID}.json)"
echo "   检查运行时是否有安全更新..."

echo ""
echo "=== 监控完成 ==="

# 症状：窗口装饰异常、缩放比例不对
# 解决方案：在 Manifest 中添加 Wayland 相关配置
{
    "finish-args": [
        "--socket=wayland",
        "--socket=fallback-x11",
        "--env=GDK_BACKEND=wayland,x11",
        "--env=QT_WAYLAND_DISABLE_WINDOWDECORATION=1"
    ]
}

# 症状：应用使用默认字体，不跟随系统字体设置
# 解决方案：
{
    "finish-args": [
        "--filesystem=xdg-config/fontconfig:ro",
        "--filesystem=~/.local/share/fonts:ro",
        "--filesystem=host-fonts:ro"
    ]
}

# 症状：应用无法读取 ~/.bashrc 中设置的环境变量
# 解决方案：使用 Portal 的 Settings 接口
# 或在 Manifest 中明确设置需要的环境变量
{
    "finish-args": [
        "--env=MY_VAR=value"
    ]
}

# 症状：Flatpak 应用比原生应用启动慢
# 可能原因：
# 1. 沙箱初始化开销
# 2. 运行时库加载
# 3. D-Bus 代理连接

# 优化方案：
# - 减少不必要的依赖
# - 使用更小的运行时
# - 预编译 GSettings schemas