🧭 OneNav 部署使用维护指南

自托管导航页 · iOS 桌面风格 · Docker 一键部署

一、项目简介

OneNav 是一个极简风格的自托管导航页应用，模拟 iOS 桌面风格，适合作为浏览器主页或书签管理工具。

核心特性

技术栈

层级技术
后端框架Python 3.11 + Flask
数据库SQLite（自动生成）
前端原生 HTML/CSS/JS + SortableJS
容器化Docker + docker compose

二、部署前准备

环境要求

提示：本指南基于第三方独立部署场景，不涉及原作者服务器信息。请将以下命令中的路径替换为你自己的实际路径。

三、部署步骤

1. 创建项目目录

mkdir -p /你的路径/docker/nav
cd /你的路径/docker/nav

2. 准备文件

在项目目录下创建以下文件：

/你的路径/docker/nav/
├── docker-compose.yml
├── Dockerfile
├── app.py
├── manifest.json
├── templates/
│   └── index.html
└── static/
    ├── icon.png        # PWA 图标（192×192 或 512×512）
    └── manifest.json
注意：data/ 目录和 nav.db 数据库文件会自动生成，无需手动创建。icon.png 需要自行准备一张方形图片，推荐 512×512 像素。

3. 关键文件内容

docker-compose.yml

services:
  nav:
    build: .
    container_name: onenav
    restart: unless-stopped
    ports:
      - "5099:5099"
    volumes:
      - ./static:/app/static
      - ./data:/app/data

Dockerfile

FROM python:3.11-alpine
WORKDIR /app
RUN pip install flask -i https://pypi.tuna.tsinghua.edu.cn/simple
COPY . .
EXPOSE 5099
CMD ["python", "app.py"]
提示：app.py 和 templates/index.html 是项目核心文件，请从项目源获取完整内容，确保包含最新的固定/取消固定功能和页面布局参数。

4. 构建并启动

cd /你的路径/docker/nav
sudo docker compose up -d --build
注意：如果遇到主目录权限错误（如 mkdir /home/xxx: permission denied），请使用： 
mkdir -p /tmp/docker-tmp
HOME=/tmp/docker-tmp sudo docker compose up -d --build

5. 验证运行

sudo docker ps | grep onenav

看到 Up 状态表示运行成功。浏览器访问 http://你的服务器IP:5099 即可使用。

四、使用指南

添加链接

  1. 点击底部右下角设置按钮（⚙️）
  2. 在弹出的表单中填写名称、选择图标、输入链接地址
  3. 点击"保存"

编辑/删除链接

  1. 手机端：长按图标约 0.5 秒，弹出菜单
  2. 电脑端：右键点击图标，弹出菜单
  3. 选择"修改"或"删除"

固定到底部 Dock

  1. 长按（或右键）上方任意图标
  2. 选择"📌 固定到底部"
  3. 图标自动移动到下方固定栏

取消固定

  1. 长按（或右键）底部已固定的图标
  2. 选择"📍 取消固定"
  3. 图标自动回到上方翻页区末尾

拖拽排序

翻页

添加到手机主屏幕（PWA）

五、日常维护

查看日志

# 查看最近日志
sudo docker logs onenav --tail 50

# 实时查看日志
sudo docker logs onenav -f

重启容器

sudo docker restart onenav

更新代码后重建

cd /你的路径/docker/nav
sudo docker compose down
sudo docker compose up -d --build

备份数据

# 数据库文件位于项目目录的 data/ 文件夹
cp -r /你的路径/docker/nav/data /你的备份路径/nav-backup-$(date +%Y%m%d)

恢复数据

# 将备份的 data/ 目录复制回项目目录
cp -r /你的备份路径/nav-backup-xxxx /你的路径/docker/nav/data
sudo docker restart onenav

修改端口

  1. 编辑 docker-compose.yml 中 ports 左侧的端口号
  2. 重建容器：sudo docker compose up -d --build

六、常见问题

Q: 页面没变化/代码没生效？

浏览器可能缓存了旧文件。尝试：

Q: 固定到底部点了没反应？

确保容器运行的是最新代码：

sudo docker exec onenav grep "pinToDock" /app/templates/index.html

如果没有输出，说明代码未更新，需要重新构建容器。

Q: 数据库可以手动编辑吗？

# 进入容器
sudo docker exec -it onenav sh

# 使用 sqlite3 操作
sqlite3 /app/data/nav.db
.tables
SELECT * FROM links;
.quit
exit
警告：手动修改数据库前请先备份，操作不当可能导致数据丢失。

Q: 如何完全卸载？

cd /你的路径/docker/nav
sudo docker compose down
cd ..
rm -rf nav

七、API 接口参考

路由方法说明
/api/linksGET获取所有链接（分 links 和 pinned）
/api/links/addPOST添加链接（name, icon, href）
/api/links/delete/<id>POST删除链接
/api/links/update/<id>POST更新链接
/api/links/sortPOST批量排序（ids 数组）
/api/links/pinPOST固定到底部（id, dock_index）
/api/links/unpinPOST取消固定（id）
示例：手动固定一个链接： 
curl -s -X POST http://localhost:5099/api/links/pin \
  -H 'Content-Type: application/json' \
  -d '{"id": 1, "dock_index": 0}'
OneNav 部署使用维护指南 · 保持更新 · 安全第一