From 9a0b95636c01247b7dda2f1ca08cf9acb8b7fab2 Mon Sep 17 00:00:00 2001 From: fuleyi Date: Mon, 17 Nov 2025 17:36:35 +0800 Subject: [PATCH] docs: add package manager hook documentation and security fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added comprehensive documentation for package manager integration to ensure automatic application list updates work correctly across different Linux distributions. The documentation explains the hook mechanism and provides configuration examples for various package managers. Additionally, security improvements were made by changing the D-Bus service ownership from root to deepin-daemon user to follow security best practices and reduce potential security risks. Log: Added package manager hook documentation and improved D-Bus service security Influence: 1. Test application list updates after installing/removing packages 2. Verify D-Bus service runs under deepin-daemon user instead of root 3. Check package manager hooks work correctly on supported distributions 4. Test application detection with different package managers 5. Verify systemd service configuration changes docs: 添加包管理器钩子文档和安全修复 添加了包管理器集成的全面文档，确保在不同 Linux 发行版上自动应用程序列表 更新功能正常工作。文档解释了钩子机制，并为各种包管理器提供了配置示例。此 外，通过将 D-Bus 服务所有权从 root 更改为 deepin-daemon 用户来进行安全改 进，遵循安全最佳实践并降低潜在安全风险。 Log: 新增包管理器钩子文档并改进 D-Bus 服务安全性 Influence: 1. 测试安装/卸载软件包后应用程序列表的更新 2. 验证 D-Bus 服务在 deepin-daemon 用户而非 root 下运行 3. 检查包管理器钩子在支持的发行版上正常工作 4. 测试不同包管理器下的应用程序检测功能 5. 验证 systemd 服务配置更改 PMS: TASK-381283 --- README.md | 25 +++++++++++++ README.zh_CN.md | 27 +++++++++++++- ...esktopspec.ApplicationUpdateNotifier1.conf | 4 +-- ...spec.ApplicationUpdateNotifier1.service.in | 2 +- ...spec.ApplicationUpdateNotifier1.service.in | 4 +-- docs/package-manager-hook.md | 35 +++++++++++++++++++ docs/package-manager-hook.zh_CN.md | 35 +++++++++++++++++++ 7 files changed, 126 insertions(+), 6 deletions(-) create mode 100644 docs/package-manager-hook.md create mode 100644 docs/package-manager-hook.zh_CN.md diff --git a/README.md b/README.md index 4b9e5f57..69e30cdd 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,31 @@ $ cmake --build build -j`nproc` sudo cmake --install build ``` +## Package Manager Integration + +**⚠️ Important for Package Maintainers and Porters** + +DDE Application Manager requires a **package manager hook** to automatically detect application installations, updates, and removals. Without this hook, the application list in the desktop environment will NOT automatically update when users install or remove applications. + +The hook triggers a D-Bus service (`app-update-notifier`) that notifies the application manager to reload the application list. This ensures the launcher, application menu, and other desktop components stay synchronized with installed packages. + +### Quick Setup + +For **Debian/Ubuntu** systems, the dpkg hook is automatically installed to: +``` +/etc/dpkg/dpkg.cfg.d/am-update-hook +``` + +For **other distributions** (Fedora, Arch Linux, openSUSE, etc.), you need to configure the appropriate package manager hook. See the detailed guide: + +📖 **[Package Manager Hook Guide](docs/package-manager-hook.md)** + +This guide includes: +- Architecture and workflow explanation +- Hook configurations for different package managers (dpkg, RPM, Pacman, etc.) +- Testing and troubleshooting instructions +- Verification checklist for package maintainers + ## Getting help * [Matrix](https://matrix.to/#/#deepin-community:matrix.org) diff --git a/README.zh_CN.md b/README.zh_CN.md index b8822f1d..609bf966 100644 --- a/README.zh_CN.md +++ b/README.zh_CN.md @@ -26,12 +26,37 @@ $ cd dde-application-manager $ cmake -B build $ cmake --build build -j`nproc` ``` -3. Install +3. 安装 ``` sudo cmake --install build ``` +## 包管理器集成 + +**⚠️ 打包维护者和移植者重要提示** + +DDE Application Manager 需要**包管理器钩子**来自动检测应用程序的安装、更新和卸载。如果没有这个钩子，当用户安装或卸载应用程序时，桌面环境中的应用程序列表将**不会**自动更新。 + +该钩子会触发一个 D-Bus 服务（`app-update-notifier`），通知应用程序管理器重新加载应用程序列表。这确保了启动器、应用程序菜单和其他桌面组件与已安装的软件包保持同步。 + +### 快速设置 + +对于 **Debian/Ubuntu** 系统，dpkg 钩子会自动安装到: +``` +/etc/dpkg/dpkg.cfg.d/am-update-hook +``` + +对于**其他发行版**（Fedora、Arch Linux、openSUSE 等），你需要配置相应的包管理器钩子。请参阅详细指南: + +📖 **[包管理器钩子指南](docs/package-manager-hook.zh_CN.md)** + +该指南包括: +- 架构和工作流程说明 +- 不同包管理器的钩子配置（dpkg、RPM、Pacman 等） +- 测试和故障排查说明 +- 打包维护者验证清单 + ## 帮助 * [Matrix](https://matrix.to/#/#deepin-community:matrix.org) diff --git a/apps/app-update-notifier/misc/dbus/org.desktopspec.ApplicationUpdateNotifier1.conf b/apps/app-update-notifier/misc/dbus/org.desktopspec.ApplicationUpdateNotifier1.conf index 92e30f58..73623a92 100644 --- a/apps/app-update-notifier/misc/dbus/org.desktopspec.ApplicationUpdateNotifier1.conf +++ b/apps/app-update-notifier/misc/dbus/org.desktopspec.ApplicationUpdateNotifier1.conf @@ -6,8 +6,8 @@ SPDX-License-Identifier: LGPL-3.0-or-later - - + + diff --git a/apps/app-update-notifier/misc/dbus/org.desktopspec.ApplicationUpdateNotifier1.service.in b/apps/app-update-notifier/misc/dbus/org.desktopspec.ApplicationUpdateNotifier1.service.in index 9d4edbd6..bfa1c0a3 100644 --- a/apps/app-update-notifier/misc/dbus/org.desktopspec.ApplicationUpdateNotifier1.service.in +++ b/apps/app-update-notifier/misc/dbus/org.desktopspec.ApplicationUpdateNotifier1.service.in @@ -5,5 +5,5 @@ [D-BUS Service] Name=org.desktopspec.ApplicationUpdateNotifier1 Exec=@CMAKE_INSTALL_FULL_LIBEXECDIR@/deepin/application-manager/app-update-notifier -User=root +User=deepin-daemon SystemdService=org.desktopspec.ApplicationUpdateNotifier1.service diff --git a/apps/app-update-notifier/misc/systemd/system/org.desktopspec.ApplicationUpdateNotifier1.service.in b/apps/app-update-notifier/misc/systemd/system/org.desktopspec.ApplicationUpdateNotifier1.service.in index d5c899ac..dea1acf2 100644 --- a/apps/app-update-notifier/misc/systemd/system/org.desktopspec.ApplicationUpdateNotifier1.service.in +++ b/apps/app-update-notifier/misc/systemd/system/org.desktopspec.ApplicationUpdateNotifier1.service.in @@ -7,7 +7,7 @@ Description=Notify by signal when Application changed by package manager. [Service] Type=dbus -User=root -Group=root +User=deepin-daemon +Group=deepin-daemon BusName=org.desktopspec.ApplicationUpdateNotifier1 ExecStart=@CMAKE_INSTALL_FULL_LIBEXECDIR@/deepin/application-manager/app-update-notifier diff --git a/docs/package-manager-hook.md b/docs/package-manager-hook.md new file mode 100644 index 00000000..8f790200 --- /dev/null +++ b/docs/package-manager-hook.md @@ -0,0 +1,35 @@ +# Package Manager Hook Guide + +## Overview + +DDE Application Manager uses a package manager hook to automatically detect application installations, updates, and removals. The hook triggers a D-Bus service that notifies the application manager to reload the application list. + +**⚠️ Without this hook, the application list will NOT automatically update when users install or remove applications.** + +## How It Works + +``` +Package Manager Operation → Hook Triggered → D-Bus Signal → Application List Reloaded +``` + +The hook calls: +```bash +busctl call org.desktopspec.ApplicationUpdateNotifier1 \ + /org/desktopspec/ApplicationUpdateNotifier1 \ + org.freedesktop.DBus.Peer Ping +``` + +## Hook Configuration + +### Debian/Ubuntu (dpkg/apt) + +File: `/etc/dpkg/dpkg.cfg.d/am-update-hook` +```bash +post-invoke="busctl call org.desktopspec.ApplicationUpdateNotifier1 /org/desktopspec/ApplicationUpdateNotifier1 org.freedesktop.DBus.Peer Ping &> /dev/null || /bin/true" +``` + +## Notes for Package Maintainers + +- The hook must be installed for automatic application list updates to work +- The hook should never fail package operations (use `|| /bin/true`) +- Ensure D-Bus service files and systemd unit files are properly installed diff --git a/docs/package-manager-hook.zh_CN.md b/docs/package-manager-hook.zh_CN.md new file mode 100644 index 00000000..e8cd0075 --- /dev/null +++ b/docs/package-manager-hook.zh_CN.md @@ -0,0 +1,35 @@ +# 包管理器钩子指南 + +## 概述 + +DDE Application Manager 使用包管理器钩子来自动检测应用程序的安装、更新和卸载。钩子触发 D-Bus 服务，通知应用程序管理器重新加载应用程序列表。 + +**⚠️ 如果没有这个钩子，当用户安装或卸载应用程序时，应用程序列表将不会自动更新。** + +## 工作原理 + +``` +包管理器操作 → 钩子触发 → D-Bus 信号 → 应用程序列表重新加载 +``` + +钩子调用: +```bash +busctl call org.desktopspec.ApplicationUpdateNotifier1 \ + /org/desktopspec/ApplicationUpdateNotifier1 \ + org.freedesktop.DBus.Peer Ping +``` + +## 钩子配置 + +### Debian/Ubuntu (dpkg/apt) + +文件: `/etc/dpkg/dpkg.cfg.d/am-update-hook` +```bash +post-invoke="busctl call org.desktopspec.ApplicationUpdateNotifier1 /org/desktopspec/ApplicationUpdateNotifier1 org.freedesktop.DBus.Peer Ping &> /dev/null || /bin/true" +``` + +## 打包维护者注意事项 + +- 必须安装钩子才能实现应用程序列表的自动更新 +- 钩子不应导致包操作失败（使用 `|| /bin/true`） +- 确保正确安装 D-Bus 服务文件和 systemd 单元文件