docs: add comprehensive README.md and fix bugs

- add README.md with usage and deployment guide - fix category sync logic in backend - fix URL overflow in admin services list - fix data caching issues in front-end and back-end - add 'View Front-end' button in admin dashboard
2026-02-13 07:00:49 +08:00
parent 872526505e
commit 521cd9ba42
10 changed files with 2884 additions and 218 deletions
--- a/README.md
+++ b/README.md
@@ -1,206 +1,69 @@
 # ToNav - 个人导航页系统

-> 一个简洁实用的个人服务导航与健康管理平台
+ToNav 是一个轻量级、简洁美观的个人内网服务/常用链接导航系统。它采用 Flask + SQLite 架构，支持响应式布局、分类管理、服务健康状态检测以及完善的后台管理功能。

-## 📋 项目概述
+## 🎨 界面风格
+继承自 `contraband_manager` 的设计语言：
+- **紫色渐变背景**: 现代感十足的视觉体验。
+- **卡片式布局**: 简洁直观的服务展示。
+- **响应式设计**: 完美适配电脑、平板及移动端。
+- **状态感知**: 实时显示服务的在线/离线状态。

-ToNav 是一个基于 Flask 的轻量级个人导航页系统，用于管理和展示内部服务，并提供服务健康状态监控功能。
+## 🚀 核心功能
+- **服务管理**: 支持添加、修改、删除服务，支持自定义图标 (Emoji)、描述和排序权重。
+- **分类管理**: 灵活的分类系统，支持分类重命名及同步更新所属服务。
+- **健康检测**: 自动检测服务 URL 的可用性，前台实时反馈（在线 🟢 / 离线 🔴）。
+- **后台管理**: 完善的 Dashboard 统计，支持修改管理员密码。
+- **防缓存机制**: API 请求自带时间戳，确保数据修改后即刻生效。

-## ✨ 核心功能
+## 🛠️ 技术栈
+- **后端**: Python 3 + Flask
+- **数据库**: SQLite 3
+- **前端**: HTML5 + CSS3 (Grid/Flexbox) + Vanilla JavaScript
+- **部署**: Systemd + Bash Control Script

-### 前台展示
- 🎨 美观的服务导航页
- 📱 响应式设计，支持移动端
- 🔖 服务分类展示
- ✅ 实时显示服务健康状态
+## 📦 安装与部署

-### 管理后台
- 🔐 安全登录系统（bcrypt 密码哈希）
- 🛠️ 服务管理（增删改查）
- 📁 分类管理
- 🔄 服务启用/禁用切换
- 🔍 手动健康检查触发
- 🔑 管理员密码修改
-
-### 健康监控
- ⏱️ 后台定时健康检查（默认 60 秒）
- 🚨 支持自定义健康检查 URL
- ⏱️ 超时控制（默认 5 秒）
- 📊 状态记录（在线/离线/超时/连接错误）
-
-## 🏗️ 技术栈
-
-| 技术 | 版本 | 用途 |
-|------|------|------|
-| Flask | 3.0.0 | Web 框架 |
-| requests | 2.31.0 | HTTP 请求（健康检查） |
-| SQLite | 内置 | 数据存储 |
-
-## 📂 项目结构
-
-```
-ToNav/
-├── app.py                  # 主应用入口
-├── config.py               # 配置文件
-├── tonav.db                # SQLite 数据库
-├── requirements.txt        # Python 依赖
-├── templates/              # HTML 模板
-│   ├── base.html          # 基础模板
-│   ├── index.html         # 前台导航页
-│   └── admin/             # 管理后台
-│       ├── login.html     # 登录页
-│       ├── dashboard.html # 仪表盘
-│       ├── services.html  # 服务管理
-│       └── categories.html # 分类管理
-├── static/                 # 静态资源
-└── utils/                  # 工具模块
-    ├── auth.py            # 认证模块
-    ├── database.py        # 数据库操作
-    └── health_check.py    # 健康检查
-```
-
-## 🗄️ 数据库结构
-
-### services 表
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | INTEGER | 自增主键 |
-| name | VARCHAR(100) | 服务名称 |
-| url | VARCHAR(500) | 服务地址 |
-| description | TEXT | 服务描述 |
-| icon | VARCHAR(50) | 图标 |
-| category | VARCHAR(50) | 所属分类 |
-| is_enabled | INTEGER | 是否启用 (1/0) |
-| sort_order | INTEGER | 排序 |
-| health_check_url | VARCHAR(500) | 健康检查地址 |
-| health_check_enabled | INTEGER | 是否启用健康检查 |
-| created_at | TIMESTAMP | 创建时间 |
-| updated_at | TIMESTAMP | 更新时间 |
-
-### categories 表
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | INTEGER | 自增主键 |
-| name | VARCHAR(50) | 分类名称 |
-| sort_order | INTEGER | 排序 |
-
-### users 表
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | INTEGER | 自增主键 |
-| username | VARCHAR(50) | 用户名 |
-| password_hash | VARCHAR(255) | 密码哈希 |
-| created_at | TIMESTAMP | 创建时间 |
-
-## 🚀 快速开始
-
-### 1. 安装依赖
+### 依赖安装
 ```bash
-cd ToNav
 pip install -r requirements.txt
 ```

-### 2. 启动服务
+### 初始化数据库
 ```bash
-python3 app.py
+python3 utils/database.py
+```
+*默认账号: `admin` / 密码: `admin123`*
+
+### 启动服务
+你可以直接使用控制脚本进行管理：
+```bash
+chmod +x tonav-ctl.sh
+./tonav-ctl.sh start
 ```

-### 3. 访问应用
- 前台导航页: http://127.0.0.1:9519
- 管理后台: http://127.0.0.1:9519/admin
- 默认账号: `admin`
- 默认密码: `tonav123`
+## ⚙️ 服务管理命令 (tonav-ctl.sh)
+- `start`: 启动服务
+- `stop`: 停止服务
+- `restart`: 重启服务
+- `status`: 查看运行状态
+- `log`: 查看最后50行日志
+- `logtail`: 实时查看日志
+- `enable`: 设置开机自启

-## ⚙️ 配置说明
-
-编辑 `config.py` 可调整以下配置：
-
-```python
-# 服务监听地址和端口
-HOST = '127.0.0.1'
-PORT = 9519
-DEBUG = False
-
-# 健康检查配置
-HEALTH_CHECK_INTERVAL = 60   # 检测间隔（秒）
-HEALTH_CHECK_TIMEOUT = 5     # 检测超时（秒）
-
-# Flask 密钥
-SECRET_KEY = 'tonav-secret-key-change-in-production-2026'
+## 📁 目录结构
+```text
+ToNav/
+├── app.py              # Flask 主应用
+├── config.py           # 系统配置文件
+├── tonav.db           # SQLite 数据库
+├── tonav-ctl.sh       # 服务管理脚本
+├── templates/          # HTML 模板
+│   ├── index.html      # 前台展示页
+│   └── admin/          # 后台管理页面
+├── static/             # 静态资源 (CSS/JS)
+└── utils/              # 数据库及认证工具类
 ```

-## 📡 API 接口
-
-### 前台 API
- `GET /api/services` - 获取所有启用的服务
- `GET /api/categories` - 获取所有分类
-
-### 后台 API
- `POST /api/admin/login` - 登录
- `GET /api/admin/login/status` - 检查登录状态
- `GET /api/admin/services` - 获取所有服务
- `POST /api/admin/services` - 创建服务
- `PUT /api/admin/services/<id>` - 更新服务
- `DELETE /api/admin/services/<id>` - 删除服务
- `POST /api/admin/services/<id>/toggle` - 切换服务状态
- `GET /api/admin/categories` - 获取所有分类
- `POST /api/admin/categories` - 创建分类
- `PUT /api/admin/categories/<id>` - 更新分类
- `DELETE /api/admin/categories/<id>` - 删除分类
- `POST /api/admin/health-check` - 手动触发健康检查
- `POST /api/admin/change-password` - 修改密码
-
-## 📊 当前数据
-
-### 已配置服务 (3 个)
-1. **违禁品查获排行榜** - http://127.0.0.1:9517
-   - 描述: 实时数据统计 · 自动刷新
-   - 图标: 📊
-   - 健康检查: ✅ 启用
-
-2. **短信接收端-Python** - http://127.0.0.1:9518
-   - 描述: HTTP接口 + Web管理
-   - 图标: 📱
-
-3. **短信接收端-Go** - http://127.0.0.1:28001
-   - 描述: 高性能版本 · 端口28001
-   - 图标: 🔧
-
-### 分类配置 (3 个)
- 内网服务
- 开发工具
- 测试环境
-
-## 🎯 使用场景
-
- 个人实验室/内网环境服务导航
- 服务状态监控面板
- 团队内部服务门户
- 自建服务启动页
-
-## 📝 注意事项
-
-1. **生产环境部署**
-   - 修改 `SECRET_KEY` 为随机字符串
-   - 修改默认管理员密码
-   - 使用反向代理（如 Nginx）
-   - 启用 HTTPS
-
-2. **健康检查**
-   - 默认仅检查 HTTP 状态码 < 500
-   - 超时服务会被标记为离线
-   - 检查间隔建议不要小于 30 秒
-
-3. **安全建议**
-   - 限制 ADMIN 接口访问
-   - 定期备份数据库
-   - 使用强密码
-
-## 📄 许可证
-
-MIT License
-
 ---
-
-**版本**: 1.0.0
-**更新时间**: 2026-02-12
+Developed for personal use. Powered by OpenClaw.