navi/README.md

瓦力导航 · wali-Navi

一个基于 Flask 的轻量级网址导航站，支持用户自定义收藏、管理员维护公共导航库、访问统计等功能。数据使用 SQLite 存储，开箱即用，可一键部署到 Docker。

功能特性

• 🔖 公共导航库：管理员可维护分类导航（搜索类 / 快捷方式类）
• 👤 用户系统：支持注册、登录、退出；普通用户可自定义个人收藏
• 🎨 自定义收藏：用户可增删改个人搜索与快捷导航，支持图标、颜色、标签、分组
• 📊 访问统计：记录每日访问量与在线人数，提供数据分析页面
• 🔍 多引擎搜索：可配置多个搜索引擎
• 🗺️ 自动 Sitemap：自动生成 sitemap.xml 便于 SEO
• 🐳 Docker 支持：提供 Dockerfile 与 docker-compose.yml 一键部署

技术栈

• 后端：Python 3.9 + Flask 2.2
• 缓存：Flask-Caching（SimpleCache）
• 服务器：gevent WSGI
• 前端：Fomantic-UI（Semantic UI）、jQuery
• 数据库：SQLite

目录结构

navi/
├── run.py              # 应用主入口
├── collect.py          # 导航数据采集脚本（参考）
├── schema.sql          # 数据库表结构
├── site.txt            # 初始导航数据（CSV 格式）
├── requirements.txt    # Python 依赖
├── Dockerfile          # 基于 python:3.9-slim 的镜像
├── Dockerfile-ubuntu   # 基于 Ubuntu 的镜像（备选）
├── docker-compose.yml  # 编排文件
├── static/             # 静态资源（CSS/JS/图片）
└── templates/          # Jinja2 模板

快速开始

本地运行

1. 安装依赖：

   pip install -r requirements.txt
   

2. 配置环境变量（可选）：

   变量名	说明	默认值
   NAVI_SECRET_KEY	Flask 会话签名密钥，生产环境务必设置	未设置时随机生成（重启失效）
   NAVI_SITE_URL	站点域名，用于生成 sitemap	空（相对路径）

   export NAVI_SECRET_KEY="your-strong-secret-key"
   export NAVI_SITE_URL="https://your-domain.com"
   

3. 启动应用：

   python run.py
   

   首次运行会自动按 schema.sql 创建数据库与表结构（生成空的 navi.db）。

4. 访问 http://localhost:18100。

默认未内置管理员账号。如需创建管理员，可在数据库生成后执行：

insert into user (username, password, status, type) values ('admin', 'your-strong-password', 1, 1);

其中 type=1 表示管理员。

Docker 部署

docker compose up -d --build

容器映射端口 18100，数据库 navi.db 通过卷挂载持久化。

初始化导航数据

site.txt 为 CSV 格式的初始导航数据，可参考 collect.py 中的逻辑将其导入 library 表。

配置说明

• 应用默认监听 0.0.0.0:18100，可在 run.py 末尾的 app.run(...) 修改。
• 缓存默认超时 300 秒，访问统计缓存 30 秒，可在 run.py 中调整。

安全建议

• 务必设置 NAVI_SECRET_KEY 环境变量，否则会话可被伪造。
• 生产环境请关闭 Flask 的 debug 模式，并使用 gevent 等生产级 WSGI 服务器（代码中已预留 WSGIServer 用法）。
• 默认管理员密码请替换为强密码。

开源协议

本项目基于 MIT License 开源。