# linux-nav

**Repository Path**: deepin20/linux-nav

## Basic Information

- **Project Name**: linux-nav
- **Description**: Linux 导航站 & ESA 管理工具：
一个包含两个子项目的仓库：
1. web/`— Linux 资源导航站（纯静态 HTML，部署到阿里云 ESA Pages）
2. tools/`— 阿里云 ESA 综合管理桌面工具（Python + tkinter）
- **Primary Language**: HTML
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://gitee.com/deepin20/linux-nav
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-13
- **Last Updated**: 2026-10-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Linux 导航站 & ESA 管理工具 & TuxNav 桌面客户端

一个包含三个子项目的仓库：

1. **`web/`** — Linux 资源导航站（纯静态 HTML + ES Module，部署到阿里云 ESA Pages）
2. **`tools/`** — 阿里云 ESA 综合管理桌面工具（Python + tkinter）
3. **`src-tauri/`** — TuxNav 桌面客户端（Tauri 2 + Rust，Debian 包分发）

## 📁 目录结构

```
linux-nav/
├── .gitignore
├── LICENSE
├── README.md
├── esa.jsonc
├── update-nav.sh               # 更新导航数据
├── update-nav-gui.sh           # 更新导航数据（GUI）
│
├── web/                        # 1. Linux 资源导航站
│   ├── index.html
│   ├── manifest.webmanifest
│   ├── sw.js
│   ├── esa.jsonc
│   ├── README.md
│   ├── wallpapers.txt
│   ├── api/
│   │   └── status.json
│   ├── css/
│   │   └── style.css
│   ├── js/
│   │   ├── main.js
│   │   ├── config.js
│   │   ├── data.js             # 站点数据（260 条）
│   │   ├── state.js
│   │   ├── i18n.js
│   │   ├── filter.js
│   │   ├── render.js
│   │   ├── favicon.js
│   │   ├── favicon-map.js
│   │   ├── utils.js
│   │   ├── music.js
│   │   ├── wallpaper.js
│   │   └── wallpaper-data.js
│   ├── images/
│   │   ├── logo.svg
│   │   ├── favicon-32.png
│   │   ├── logo-192.png
│   │   ├── logo-512.png
│   │   ├── logo-180.png
│   │   ├── favicons/
│   │   ├── l265/
│   │   └── wallpapers/
│   └── audio/
│
├── tools/                      # 2. ESA 综合管理桌面工具
│   ├── esa_manager.py
│   ├── esa_manager/
│   │   ├── alidns.py
│   │   ├── api.py
│   │   ├── app.py
│   │   ├── credentials.py
│   │   ├── gitee.py
│   │   ├── helpers.py
│   │   ├── pages.py
│   │   └── tabs/
│   │       ├── analytics.py
│   │       ├── bind.py
│   │       ├── cert.py
│   │       ├── deploy.py
│   │       ├── icp.py
│   │       ├── onestep.py
│   │       ├── records.py
│   │       ├── routines.py
│   │       └── sites.py
│   ├── nav_updater.py
│   ├── nav_updater_gui.py
│   ├── requirements.txt
│   └── README.md
│
├── src-tauri/                  # 3. TuxNav 桌面客户端
│   ├── Cargo.toml
│   ├── tauri.conf.json
│   ├── build.rs
│   ├── capabilities/
│   │   └── default.json
│   ├── icons/
│   └── src/
│       ├── main.rs
│       └── lib.rs
│
├── scripts/
│   ├── prepare-web.sh
│   ├── apply-theme-css.py
│   └── gen-fake-status.py
│
├── web-tools/
│   ├── validate-data.mjs
│   ├── check-https.mjs
│   ├── serve.py
│   ├── download-favicons.py
│   ├── download-wallpapers.py
│   ├── compress-audio.sh
│   ├── reports/
│   └── wallpapers.txt
│
└── docs/
    └── screenshots/
        ├── web-preview.png
        └── tool-preview.png
```

## 🚀 快速开始

### 一、导航站（web/）

**本地预览**

必须通过 HTTP 服务访问（ES Module 有 CORS 限制）：

```bash
cd web
python3 -m http.server 8080
```

浏览器打开 <http://localhost:8080/>。

**部署到阿里云 ESA Pages**

1. 登录 [ESA 控制台](https://esa.console.aliyun.com/)
2. 进入「函数和 Pages」→「创建项目」
3. 选择「导入 Gitee 仓库」，授权并选择本仓库
4. **根目录填 `web`**（重要：否则找不到 `esa.jsonc`）
5. 构建命令留空或填 `exit 0`
6. 输出目录填 `./`
7. 点击部署，等待完成后获得默认域名
8. 后续按 ICP 备案 → 绑定 `tuxnav.cn` → 配置 CNAME → 开启 HTTPS 的流程上线

**功能特性**

- 收录 **260 个** 精选 Linux 相关站点
- 按类型 / 发行版家族 / 地域三维标签筛选
- 搜索与筛选联动，支持 URL 参数分享（`?q=ubuntu&tags=distro,debian`）
- 数据驱动，新增站点只需在 `SITES` 数组加一行
- 响应式布局，桌面端多列、移动端单列
- 回到顶部、组合筛选、实时结果计数
- **收藏夹**：一键收藏，支持导出/导入 JSON
- **深色/浅色主题**：☀️ 浅色 / 🌙 深色 / 🌗 跟随系统
- **自定义分类排序**：拖拽调整首页展示顺序
- **站点状态检测**：失效站点显示 ⚠️ 并降权
- **背景音乐 + 动态壁纸**（附加功能）
- 纯原生 CSS + JS，**无 CDN 依赖**，离线可用

### 二、Python 桌面工具（tools/）

**安装依赖**

```bash
cd tools
pip install -r requirements.txt
```

**运行**

```bash
python esa_manager.py
```

**打包成可执行文件（可选）**

不同平台打包产物不同：

```bash
pip install pyinstaller
pyinstaller -F -w -n ESA管理器 esa_manager.py
```

生成的可执行文件位于 `dist/` 目录下：

| 平台 | 产物文件名 |
|---|---|
| Windows | `ESA管理器.exe` |
| Linux / macOS | `ESA管理器`（无后缀） |

> ⚠️ 各平台只能打包出对应平台的可执行文件，不能跨平台运行。

**完整功能说明见 [`tools/README.md`](tools/README.md)**，包括：

- 单域名 / 批量域名绑定
- 解析记录查询 / 修改 / 删除
- SSL 证书申请
- ICP 备案查询
- 凭证持久化

### 三、TuxNav 桌面客户端（src-tauri/）

**系统依赖**

```bash
sudo apt update
sudo apt install -y \
  libwebkit2gtk-4.1-dev \
  build-essential \
  curl wget file \
  libxdo-dev libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev
```

**安装 Rust 和 Tauri CLI**

```bash
# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Tauri CLI
npm init -y
npm install -D @tauri-apps/cli@latest
```

**开发模式**

```bash
npx tauri dev
```

首次编译约 5-10 分钟。成功后弹出 TuxNav 窗口。

**打包 .deb**

```bash
npx tauri build
```

输出：

```
src-tauri/target/release/bundle/deb/tuxnav_1.1.0_amd64.deb
```

**安装**

```bash
sudo dpkg -i tuxnav_1.1.0_amd64.deb
sudo apt install -f  # 如有依赖缺失
```

启动：开始菜单搜索 "TuxNav" 或命令行运行 `tuxnav`。

**桌面端专属功能**

- **系统托盘**：关闭窗口最小化到托盘
- **全局快捷键**：`Ctrl+Shift+T` 一键唤起
- **单实例**：重复启动时聚焦已有窗口
- **离线模式**：本地打包，首屏 < 1 秒
- **收藏夹备份**：原生文件对话框，导出/导入 JSON

## 🛠️ 开发工具

### 数据校验

```bash
# 校验 data.js 完整性（必填字段、URL 格式、标签合法性、重复条目）
node web-tools/validate-data.mjs --strict

# 检测所有站点可用性
python3 web-tools/serve.py --check-only

# HTTPS 探测
node web-tools/check-https.mjs
```

### 图标与资源

```bash
# 批量下载站点 favicon
python3 web-tools/download-favicons.py

# 下载壁纸
python3 web-tools/download-wallpapers.py

# 压缩音频
cd web && bash compress-audio.sh
```

### 更新导航数据

```bash
bash update-nav.sh          # 命令行版
bash update-nav-gui.sh      # GUI 版
```

## 📦 版本历史

### v1.1.0（当前）

**新增功能**

- 离线模式：本地打包，首屏 < 1 秒
- 深色/浅色主题手动切换
- 收藏夹导出/导入（原生文件对话框）
- 自定义分类排序（拖拽）
- 站点失效自动检测

**UI 优化**

- 工具栏图标 emoji → SVG
- 应用图标全新企鹅 Logo
- 新增友情链接区块

**技术改进**

- 应用体积：5 MB → 18 MB（含离线资源）
- favicon 覆盖率：70% → 95%
- 依赖插件：5 → 7 个

### v1.0.0

- 首次发布
- 260 个精选站点
- 基础筛选、收藏、搜索

## 🔒 安全提醒

**绝对不要**把以下文件提交到仓库：

- `~/.esa_manager_creds.json`（包含 AK/SK 明文）
- 任何 `.env` 文件
- 任何包含 `access_key_id` / `access_key_secret` 的文件

`.gitignore` 已经默认排除这些文件，但仍需在提交前用 `git status` 再确认一次。

如果误提交了凭证：

1. **立即**登录阿里云 RAM 控制台，禁用并删除泄露的 AccessKey
2. 用 `git filter-repo` 或 BFG 清理 Git 历史
3. 或者直接删除仓库重建

## 🛠️ 环境要求

| 子项目 | 要求 |
|---|---|
| web/ | 任意现代浏览器；部署需要 ESA 账号 + 已备案域名 |
| tools/ | Python ≥ 3.7；网络可访问阿里云 API |
| src-tauri/ | Rust 1.77+；Node.js 18+；Linux 系统依赖 |
| web-tools/ | Node.js 18+ / Python 3.7+ |

## 📄 许可证

本项目采用 [MIT License](LICENSE)。

### 资源版权说明

- **站点信息**：来自各站点公开信息，版权归原站点所有
- **favicon**：通过公开 API 获取，版权归原站点所有
- **壁纸**：来源见 `web/wallpapers.txt`，仅用于学习演示
- **音乐**：来源见 `web/audio/` 目录，仅用于学习演示，请勿商用

如涉及版权问题，请联系删除。

## 🙏 致谢

- 站点数据参考 [DistroWatch](https://distrowatch.com)、[LinuxLinks](https://www.linuxlinks.com) 及各大开源社区
- 桌面客户端基于 [Tauri](https://tauri.app/) + [Rust](https://www.rust-lang.org/)
- [Linux265 资源分享网](https://www.linux265.com/) — 友情链接
- 阿里云 SDK 由 [Alibaba Cloud](https://github.com/aliyun) 提供

## 📮 反馈

如有问题或建议，欢迎在 Gitee 提交 Issue：

<https://gitee.com/deepin20/linux-nav/issues>

---

**TuxNav · 精选 · 权威 · 活跃**