# Deepin 社区助手

**Repository Path**: deepin20/deepin-community-py

## Basic Information

- **Project Name**: Deepin 社区助手
- **Description**: Deepin 社区助手：一款专为统信 UOS / Deepin 打造的轻量级、高集成度的 Deepin 官方论坛非官方桌面客户端。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/deepin20/deepin-community-py
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Deepin 社区助手

> 一款专为统信 UOS / Deepin 打造的轻量级、高集成度的 Deepin 官方论坛非官方桌面客户端。

[![Version](https://img.shields.io/badge/version-1.2.0-blue)](https://gitee.com/deepin20/deepin-community-py)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
[![Framework](https://img.shields.io/badge/framework-PyQt6-green)](https://www.riverbankcomputing.com/software/pyqt/)
[![License](https://img.shields.io/badge/license-Proprietary-lightgrey)](./debian/copyright)

---

## 📸 预览

![输入图片说明](202609180519565450_VirtualBox_deepin25_18_09_2026_13_16_24.png)

---

## ✨ 功能特性

- **🌐 一体化内置浏览器** —— 首页、发帖、消息、个人中心全部采用 `QWebEngineView` 内嵌 Chromium，支持登录、发帖、浏览原汁原味的论坛页面。
- **📂 原生版块导航** —— 论坛所有分类采用原生卡片式排版，支持鼠标悬停与点击跳转，体验贴近桌面原生应用。
- **📊 实时数据抓取** —— 自动抓取并实时显示各版块的"主题数"、"帖数"及"当日发帖数"，附带本地缓存离线兜底。
- **🧭 自定义导航历史栈** —— 修复了 QtWebEngine 在 `createWindow` 场景下历史记录缺失的问题，后退 / 前进按钮完全可靠。
- **🖱️ 统信 UOS 原生适配** —— 适配高分屏缩放（HiDPI），侧边栏样式、窗口居中、任务栏中文名均已调优。
- **🧹 资源管理清晰** —— 解决了 WebEngine 在 UOS 下的内存泄漏、UI 重叠与渲染进程崩溃自愈问题。
- **📦 符合 UOS 应用商店规范** —— 安装路径遵循 `/opt/apps/<appid>/` 布局，可直接构建 `.deb` 安装包。

---

## 🖥️ 支持的系统

| 系统 | Python | PyQt6 版本 | 状态 |
|---|---|---|---|
| **Deepin 25 (crimson)** | 3.12 | 最新版（如 6.11） | ✅ 完整支持 |
| **Deepin 23** | 3.11 | 6.6 ~ 6.7 | ✅ 完整支持 |
| **UOS 20 / Deepin 20** | 3.7（需 Miniconda 升到 3.12） | **必须 6.5.0** | ✅ 完整支持（见下方指南） |
| **Ubuntu / Debian / Fedora / Arch** | 3.8+ | 6.5+ | ⚠️ 理论可行，未充分测试 |

---

## 🚀 快速开始

### 1. 克隆或下载项目

```bash
git clone https://gitee.com/deepin20/deepin-community-py.git
cd deepin-community-py
```

### 2. 安装依赖（选择对应系统的命令）

#### 🐧 Deepin 25 / 新系统

```bash
/usr/bin/python3 -m pip install --user --break-system-packages \
    PyQt6 PyQt6-WebEngine
```

#### 🐧 Deepin 23

```bash
/usr/bin/python3 -m pip install --user PyQt6 PyQt6-WebEngine
```

#### 🐧 UOS 20 / Deepin 20（系统 Python 3.7 太老）

需先安装 **Miniconda** 创建一个 Python 3.12 环境：

```bash
# 1. 下载并安装 Miniconda
cd ~/Downloads
wget https://mirrors.ustc.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3

# 2. 配置 conda-forge 频道（避免 Anaconda 商业条款）
cat > $HOME/.condarc <<'EOF'
channels:
  - conda-forge
channel_priority: strict
show_channel_urls: true
EOF

# 3. 创建 Python 3.12 环境
$HOME/miniconda3/bin/conda create -y -n dcp \
    --override-channels -c conda-forge python=3.12

# 4. 装 PyQt6 6.5.0（6.6+ 需要 glibc 2.35+，UOS 20 是 2.28，会崩溃）
$HOME/miniconda3/envs/dcp/bin/pip install \
    --index-url https://pypi.org/simple/ --prefer-binary \
    'PyQt6==6.5.0' 'PyQt6-WebEngine==6.5.0' \
    'PyQt6-Qt6==6.5.0' 'PyQt6-WebEngine-Qt6==6.5.0'
```

> ⚠️ **必须用 `--index-url https://pypi.org/simple/` 加 `--prefer-binary`**。国内镜像上 PyQt6 常常只有源码包，pip 会尝试现场编译，而编译需要 Qt6 开发环境，必然失败。

#### ✅ 验证依赖

```bash
# 根据你的系统选择解释器
/usr/bin/python3 -c "from PyQt6.QtWebEngineWidgets import QWebEngineView; print('✅ WebEngine OK')"
# 或 UOS 20：
$HOME/miniconda3/envs/dcp/bin/python -c "from PyQt6.QtWebEngineWidgets import QWebEngineView; print('✅ WebEngine OK')"
```

看到 `✅ WebEngine OK` 就可以启动。

### 3. 运行

```bash
./run.sh
```

`run.sh` 会自动：
1. 从候选列表挑一个「装了 PyQt6 + WebEngine」的解释器（conda 环境优先）；
2. 把 pip 用户级 site-packages 挂进 `PYTHONPATH`；
3. 启动 `main.py`。

若需要指定特定解释器：

```bash
DEEPIN_COMMUNITY_PYTHON=/usr/bin/python3 ./run.sh
```

### 4. 屏蔽浏览器警告

Chromium 内核启动时会产生大量 `js: Deprecated API` 警告。加上 `2>/dev/null` 保持终端干净：

```bash
./run.sh 2>/dev/null
```

---

## 📦 打包为 .deb

> 遵循 UOS 应用商店规范，安装路径为 `/opt/apps/org.deepin.community.helper/`。

### 一键打包

```bash
./build-deb.sh              # 打包
./build-deb.sh --install    # 打包 + 安装
./build-deb.sh --no-lintian # 跳过 lintian 检查（更快）
./build-deb.sh --clean-only # 只清理，不打包
./build-deb.sh --help       # 显示帮助
```

产物生成在项目上一级目录，同时归档到 `dist/`。

### 手动打包

```bash
# 1. 清理
find . -name '__pycache__' -type d -prune -exec rm -rf {} + 2>/dev/null
find . -name '*.pyc' -delete 2>/dev/null

# 2. 打包
dpkg-buildpackage -b -us -uc
```

### 安装

**方式一（推荐）**：双击 `.deb` 文件，走系统图形化安装器。

**方式二**：命令行

```bash
sudo apt install ./org.deepin.community.helper_1.2.0_all.deb
```

> ⚠️ **deepin 23 / UOS 20 用户**：若 apt 报 `libqt6test6 ... 404`，说明系统仓库中该包已下架（系统级问题）。改用 dpkg 强制安装：
>
> ```bash
> sudo dpkg -i --force-depends ./org.deepin.community.helper_1.2.0_all.deb
> ```
>
> 本应用实际用 pip 装的 PyQt6，**不依赖**系统的 `python3-pyqt6`。

### 启动已安装的应用

从应用菜单点击「Deepin 社区助手」，或命令行：

```bash
DEEPIN_COMMUNITY_PYTHON=/usr/bin/python3 \
    /opt/apps/org.deepin.community.helper/files/run.sh
```

> UOS 20 用户：把 `/usr/bin/python3` 换为 `$HOME/miniconda3/envs/dcp/bin/python`。

### 卸载

```bash
sudo dpkg -r org.deepin.community.helper
```

---

## 🐧 其他发行版运行方案

若要在 Ubuntu / Fedora / Arch 等发行版运行，除了 pip 装 PyQt6 外，还有两种打包方案正在规划中：

- **AppImage** —— 单文件、免安装，兼容大多数发行版；
- **玲珑包（Linglong）** —— deepin 25 引入的新一代包格式，自带沙箱和共享运行时。

> 这两个方案尚未落地，欢迎有兴趣的贡献者提交 PR。

---

## 📁 项目结构

```text
deepin-community-py/
├── run.sh                                  # 启动脚本（自动选解释器 + 路径自愈）
├── build-deb.sh                            # 一键打包脚本
├── main.py                                 # 程序主入口（环境变量、路径自愈、启动）
├── config.py                               # 本地配置读写（settings / cache / debug_log）
├── requirements.txt                        # Python 依赖声明
├── README.md                               # 本文件
├── CHANGELOG.md                            # 更新日志
├── .gitignore
├── org.deepin.community.helper.svg         # 应用图标（桌面 scalable 源）
│
├── core/                                   # 核心逻辑层
│   ├── __init__.py                         # 零 Qt 依赖（避免打乱环境变量时序）
│   ├── application.py                      # QApplication 封装（应用名 / 版本号）
│   ├── main_window.py                      # 主窗口、侧边栏、路由、内置浏览器
│   └── version.py                          # 版本号单一来源
│
├── ui/                                     # UI 视图层
│   ├── __init__.py                         # 零 Qt 依赖
│   └── forum_page.py                       # 版块导航 + 实时数据抓取
│
├── widgets/                                # 自定义组件
│   ├── __init__.py
│   └── forum_card.py                       # 版块卡片（图标 / 标题 / 统计 / 右键菜单）
│
├── resources/icons/                        # 各尺寸 PNG 图标（16 ~ 512）
│
├── tests/
│   └── test_minimal.py                     # 手动探针：最小 WebEngine 启动测试
│
└── debian/                                 # 打包配置
    ├── changelog
    ├── control
    ├── copyright
    ├── info                                # UOS 应用商店 JSON 描述
    ├── install
    ├── org.deepin.community.helper.desktop
    ├── postinst
    ├── rules
    └── source/
        └── format
```

---

## 🔧 开发说明

### 版本号管理

版本号采用**单一来源**，只需改 `core/version.py`：

```python
__version__ = "1.2.0"
```

窗口标题栏、启动日志、`QApplication.applicationVersion()` 会自动同步。
`debian/changelog` 需单独维护（Debian 打包体系要求）：

```bash
dch -v 1.2.1 "本次更新的简要说明"
```

### 调试模式

启动时带 `DCP_DEBUG=1`，会在终端打印生命周期日志（应用版本、平台后端、Chromium flags、共享 OpenGL 上下文、页面切换、事件循环退出等），便于排查崩溃 / 卡死：

```bash
DCP_DEBUG=1 ./run.sh
```

### 修改后重新打包

```bash
./build-deb.sh --no-lintian
```

---

## ❓ 常见问题

### Q1：启动报 `ModuleNotFoundError: No module named 'PyQt6.QtWebEngineWidgets'`

**原因**：PyQt6 主包装了，但 WebEngine 绑定没装（或装到了另一个解释器）。

**解决**：两个包必须在**同一条命令**里一起装：

```bash
/usr/bin/python3 -m pip install --user PyQt6 PyQt6-WebEngine
```

### Q2：启动报 `undefined symbol: gbm_bo_get_fd_for_plane`

**原因**：PyQt6 6.6+ 需要 glibc 2.35+，而 UOS 20 / deepin 20 是 glibc 2.28。

**解决**：降级到 6.5.0：

```bash
/usr/bin/python3 -m pip install --user \
    'PyQt6==6.5.0' 'PyQt6-WebEngine==6.5.0'
```

### Q3：终端里全是 `js: [Report Only] Refused to load...` 警告

**原因**：Deepin 论坛的 CSP 策略与内置 Chromium 冲突。**对功能没有任何影响**。

**解决**：

```bash
./run.sh 2>/dev/null
```

### Q4：窗口打开后不能拖拽移动

**原因**：`QT_QPA_PLATFORM=xcb` 在某些 UOS 主题下会禁用窗口装饰拖拽。

**解决**：按住 `Alt` + 鼠标左键拖拽。或尝试改用 `dxcb`：

```bash
QT_QPA_PLATFORM=dxcb ./run.sh
```

若报 `Could not find the Qt platform plugin "dxcb"`，回退到 `xcb`。

### Q5：版块数据一直显示"加载中"

**原因**：后端防火墙升级，或内网连接超时。

**解决**：程序内置 20 秒超时，超时后会自动变为"连接超时"。点击右上角"刷新"重试。

### Q6：为什么启动参数带 `--no-sandbox`？

为了在部分 UOS 内核上获得更好的稳定性而保留的防御性配置（见 `main.py` 注释）。它会关闭 Chromium 沙箱，是**安全性换稳定性**的取舍。若你所在环境对安全要求较高，可删除 `main.py` 中 `QTWEBENGINE_CHROMIUM_FLAGS` 里的这一项后自行测试。

### Q7：如何查看当前运行的版本号？

三种方式：

1. **窗口标题栏** —— 显示 `Deepin 社区助手 v1.2.0`；
2. **启动日志** —— `DCP_DEBUG=1 ./run.sh` 首行打印 `[调试] Deepin 社区助手 v1.2.0`；
3. **包管理器** —— `dpkg -l org.deepin.community.helper`。

### Q8：apt 报 `libqt6test6 ... 404 Not Found`

**原因**：deepin 23 仓库里这个包已下架，是仓库自身的问题，不是 `.deb` 的问题。

**解决**：改用 `dpkg -i --force-depends`：

```bash
sudo dpkg -i --force-depends ./org.deepin.community.helper_1.2.0_all.deb
```

### Q9：国产 CPU 架构（ARM / LoongArch）上能跑吗？

**原理上可以**，但当前 pip 源上不一定有对应架构的 PyQt6 预编译 wheel。若 pip 报 `No matching distribution found`，需自行从源码编译 PyQt6（需要 Qt6 开发环境，工作量大）。

---

## 📄 许可证

本项目仅供个人学习与交流使用，严禁用于任何商业用途。详见 [`debian/copyright`](./debian/copyright)。

---

## 🙏 致谢

感谢所有反馈导航按钮失效、图标异常、安装失败问题的用户。本项目大部分修复都源于实际使用中暴露的问题，欢迎继续反馈。

- 项目主页：https://gitee.com/deepin20/deepin-community-py
- 问题反馈：https://gitee.com/deepin20/deepin-community-py/issues
- 更新日志：[CHANGELOG.md](./CHANGELOG.md)