Hana

文档

Hana 新手指南。

从安装到第一个链接,再到 AI——一步步来。

Hana 是什么?

Hana 收好你想记住的链接——文章、工具、视频——并能很快重新找到。

它是你自己的私人书签应用,跑在你掌控的电脑上,数据存在你自己的数据库里。

开始之前

你需要两样东西。

一台常开的电脑

Mac、Windows 或 Linux 都行。只有这台电脑醒着时,Hana 才能访问。

Docker Desktop

一个免费软件,把 Hana 装进独立的盒子里运行。到 docker.com 下载、安装、打开一次。

→ Docker 显示绿色「running」时即就绪。

安装 Hana

在终端(Mac)或 PowerShell(Windows)里逐条输入,每条按回车。

1 — 下载

git clone https://github.com/Cole404/hana.git
cd hana

→ 没有 git?在 GitHub 点 Code → Download ZIP,解压后 `cd ` 进该文件夹。

2 — 创建配置文件

cp .env.example .env

3 — 设置密钥

生成一段长随机值,粘贴到 .env 里 AUTH_SECRET= 后面,保存。

openssl rand -base64 32

4 — 启动

第一次运行需要几分钟。

docker compose up -d

5 — 打开

访问 http://localhost:3000。完成。

你的第一批书签

账号

用邮箱和密码注册,只存在你自己的服务器上。

保存链接

点 +,粘贴网址。新链接落进收件箱。

文件夹

把链接归进文件夹,可任意嵌套,拖拽归类或排序。

搜索

搜索标题和网址。中英文皆可,容忍拼写错误和缩写。

导入旧书签

  1. 1.从浏览器把书签导出成 HTML 文件。
  2. 2.在 Hana 打开导入,选择该文件。
  3. 3.随时导出 HTML 或 JSON 备份或迁出。

浏览器扩展

不打开 Hana 也能保存当前网页。

  1. 1.在 Hana:设置 → 访问密钥,创建一个密钥。
  2. 2.在 Chrome:打开 chrome://extensions,开启开发者模式。
  3. 3.点「加载已解压的扩展程序」,选 clients/extension 文件夹。
  4. 4.固定图标,打开设置,粘贴密钥。

AI(可选)

接入你自己的 AI 账号,获得按含义搜索、自动归类和聊天。费用按服务商用量计。

获取 API 密钥

在服务商的开发者页面创建。Hana 支持任何兼容 OpenAI 或 Anthropic 的服务,包括 Ollama 等本地服务。

在设置 → AI 填入

  1. 1.语义搜索:填服务地址、嵌入 API 密钥和模型名。
  2. 2.AI 聊天:选协议,填地址和密钥,选模型(点「获取模型」可列出)。

字段填好后各功能自动开启。密钥加密存储,只发给你选定的服务商。

  • 语义搜索 —— 用一句描述找到链接。
  • 自动归类 —— 保存时建议文件夹,并从修正中学习。
  • 聊天助手 —— 先给方案,确认后执行,每步可撤销。

命令行与 API

可选的高阶工具。

  • CLI —— hana 命令,在终端保存和批量操作。
  • Agent API —— 给其他程序或 AI 代理(MCP)用的安全接口,用同一个访问密钥。

→ 两者都在 clients 文件夹下,各带一份安装说明。

让 Hana 持续运行

从其他设备访问

把 localhost 换成主机的本地 IP,例如 http://192.168.1.20:3000。要走互联网,加域名和 HTTPS(见 README)。

备份

导出 HTML 或 JSON。数据也在 Docker 管理的 PostgreSQL 数据库里。

更新

拉取并重启,迁移会自动应用。

git pull
docker compose up -d --build

关闭注册

在 .env 设置 REGISTRATION_ENABLED=false 并重启。

忘记密码

用登录页上的链接(需在 .env 配置邮件服务)。

常见问题

localhost:3000 打不开

首次构建稍等一两分钟,并确认 Docker 在运行。日志:docker compose logs -f。

端口被占用

在 docker-compose.yml 改端口(如 3001),或关掉占用 3000 的程序。

AI 没反应

再查设置 → AI 里的地址和密钥,以及服务商余额。试试「获取模型」。

数据安全吗?

安全——都留在你的数据库里。不开 AI 就没有数据外发。