开发工具【免费下载链接】buku:bookmark: Personal mini-web in text项目地址https://gitcode.com/gh_mirrors/bu/buku点击查看免费下载导读本文以 bukuserverBuku 书签数据库的官方 Web 管理界面为核心系统讲解从 pip/PyPI、源码、Docker 到 Docker Compose 的四种部署路径逐项剖析BUKUSERVER_前缀环境变量配置体系分页、主题、favicon、只读模式、反向代理等并完整梳理基于 Flask 的 RESTful API 端点与实战调用方式。读完本文你将能够独立部署一套可访问的书签 Web 服务按需定制界面行为并通过/api接口对书签、标签做增删改查与远程数据抓取。目录Bukuserver 是什么安装指南依赖准备从 PyPI 安装从源码安装使用 Docker 部署使用 Docker Compose 部署启动 Web 服务器Webserver options环境变量配置体系配置变量速查表如何指定环境变量布尔值与非法输入的兜底规则为什么默认禁用 faviconRESTful API 接口API 端点总览JSON 与 urlencoded 请求格式说明接口背后的实现机制界面与统计Bukuserver 是什么Buku 是一款在终端里运行的轻量级书签管理器个人迷你 WebPersonal mini-web in text而 bukuserver 则是它的 Web 图形界面与 HTTP API 层。bukuserver 基于 Flask 与 Flask-Admin 构建把 Buku 的 SQLite 书签数据库暴露为一个可浏览、可检索、可管理的网页应用并同时提供一套完整的 RESTful API供脚本、Agent 或第三方程序以编程方式读写书签与标签。其核心代码位于仓库的 bukuserver/ 目录入口模块为 server.py其中create_app()负责装配 Flask 应用、注册管理视图与全部 API 路由。整个服务依赖的核心包见 bukuserver/requirements.txtFlask、Flask-Admin、flask-paginate、Flask-WTF、flasggerSwagger 文档生成、arrow 等。安装指南依赖准备在安装bukuserver之前请先确保系统已具备以下基础软件包来自发行版软件源python3python3-pippython3-devlibffi-dev开发环境建议先创建并激活虚拟环境# venv 激活用于开发 $ python3 -m venv venv $ source venv/bin/activate $ pip install --upgrade pip激活虚拟环境后后续安装与启动均在 venv 中进行可避免污染系统 Python 环境。从 PyPI 安装buku[server]是带 server 扩展的安装方式等价于把 bukuserver 及其全部运行依赖一并装好# 常规 / venv 安装 $ pip3 install buku[server] # pipx 安装隔离的应用级环境 $ pipx install buku[server] # 带语言包GUI 多语言安装 $ pipx install buku[server,locales]注意locales扩展是启用 GUI 多语言即BUKUSERVER_LOCALE环境变量的前提详见下文配置章节。从源码安装如果你希望直接从本仓库源码安装便于调试或跟随最新开发版本$ git clone https://github.com/jarun/buku $ cd buku # 常规 / venv 安装 $ pip3 install .[server] # 带语言包 $ pip3 install .[server,locales]使用 Docker 部署在仓库根目录构建镜像docker build -t bukuserver .运行镜像数据持久化到宿主机目录docker run -it --rm -v ~/.local/share/buku:/root/.local/share/buku -p 5001:5001 bukuserver容器内生成的所有数据都会存储在~/.local/share/buku目录中你可以把它替换为任意你希望存放数据库的完整路径。浏览器访问127.0.0.1:5001即可打开你的书签页面。数据卷挂载的设计与 Buku 的默认数据库目录一致——从 server.py 可以看到当未指定DB_FILE时BukuDb会落在标准 DB 目录即~/.local/share/buku因此把该目录挂载出来即可保证容器重建后数据不丢失。使用 Docker Compose 部署仓库根目录的 docker-compose/docker-compose.yml 提供了一站式编排方案bukuserver 服务 nginx 反向代理docker-compose up -d启动后 bukuserver 将运行在宿主机80 端口经 nginx 反代。停止服务docker-compose downcompose 文件中预置了常用环境变量示例见environment段例如BUKUSERVER_PER_PAGE100、BUKUSERVER_OPEN_IN_NEW_TABtrue以及被注释掉的BUKUSERVER_SECRET_KEY、BUKUSERVER_URL_RENDER_MODE、BUKUSERVER_DISABLE_FAVICON取消注释即可启用对应行为数据卷将./data挂载到容器内的~/.local/share/buku。为托管实例增加 Basic Auth 认证在data/basic_auth目录下创建.htpasswd文件并添加用户htpasswd -c data/basic_auth/.htpasswd your_username取消 data/nginx/nginx.conf 中这两行 Basic Auth 配置的注释#auth_basic Administrators Area; #auth_basic_user_file /basic_auth/.htpasswd;该 nginx 配置同时把请求反向代理到http://bukuserver:5001并正确传递Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto等头这为下文BUKUSERVER_REVERSE_PROXY_PATH、BUKUSERVER_SERVER_NAME等生产环境配置提供了基础。更完整的 nginx 文档请参考 nginx 官方 Basic Authentication 指南。启动 Web 服务器Webserver options以默认主机 127.0.0.1、端口 5001 启动服务器$ bukuserver run --host 127.0.0.1 --port 5001浏览器访问127.0.0.1:5001即可使用。更多选项可查看bukuserver run --help与bukuserver --help。从源码角度看CLI 由 server.py 中的click.group(clsCustomFlaskGroup, create_appcreate_app)定义--version参数会输出 buku 版本、Flask 版本与 Python 版本信息见get_custom_version。环境变量配置体系Bukuserver 的全部运行参数通过环境变量注入所有变量共享统一前缀BUKUSERVER_。它们最终在 server.py 的create_app()中被读取并写入app.config因此可以直接对应到 Flask 配置键。配置变量速查表名称不含前缀描述取值 ²PER_PAGE每页显示的书签条数正整数 [默认: 10]SECRET_KEYFlask 密钥字符串 [默认: 随机值]URL_RENDER_MODEURL 渲染模式full、netloc或netloc-tag[默认:full]DB_FILE数据库文件的完整路径 ³路径字符串 [默认: buku 标准路径]READONLY只读模式布尔 ¹ [默认:false]DISABLE_FAVICON禁用书签 favicon布尔 ¹ [默认:true]原因见下文AUTOFETCH新建表单中 Fetch 的初始值布尔 ¹ [默认:true]OPEN_IN_NEW_TAB书签链接是否在新标签页打开布尔 ¹ [默认:false]REVERSE_PROXY_PATH反向代理路径前缀 ⁵字符串SERVER_NAME用于生成 URL 的规范 host:port ⁶字符串如example.com:443THEMEGUI 主题字符串 [默认:default]暗色模式推荐slateLOCALEGUI 语言 ⁴部分支持字符串 [默认:en]DEBUG调试模式详细日志等布尔 ¹ [默认:false]¹ 合法的布尔值为true、false、1、0不区分大小写。² 若输入非法则回退到已定义的默认值。³BUKUSERVER_DB_FILE可以是数据库名不含扩展名的纯文件名且不能包含.。此时程序会在默认数据库目录中定位name.db文件该目录可通过BUKU_DEFAULT_DBDIR覆盖。⁴ 启用BUKUSERVER_LOCALE需要 buku 以[locales]扩展安装。⁵BUKUSERVER_REVERSE_PROXY_PATH建议以/开头且不以/结尾即用/foo而不要用/foo/。⁶BUKUSERVER_SERVER_NAME可缓解 Host 头注入 攻击。设置后生成绝对 URL如 bookmarklet时将使用该值而非客户端提供的 Host 头。生产环境与反向代理部署强烈推荐设置。如何指定环境变量例如将每页书签数设置为 100# Linux $ export BUKUSERVER_PER_PAGE100 # Windows $ SET BUKUSERVER_PER_PAGE100 # Dockerfile 内 ENV BUKUSERVER_PER_PAGE100 # env 文件内 BUKUSERVER_PER_PAGE100env 文件有两种提供方式通过 Flask CLI 的--env-file参数需要安装python-dotenv作为 runner 脚本的配置见仓库中的 bukuserver-runner/ 目录及其 buku-server.py该脚本封装了更高级的安装、运行与数据库切换功能。布尔值与非法输入的兜底规则源码中布尔解析由get_bool_from_env_var实现server.py内部维护{true: True, 1: True, false: False, 0: False}映射取环境变量的小写形式查找查不到则使用调用方传入的默认值。其他数值/枚举变量如PER_PAGE、URL_RENDER_MODE、THEME同样遵循非法输入回退默认值的规则server.py其中PER_PAGE若 0则回退到 views.py 中定义的DEFAULT_PER_PAGE 10URL_RENDER_MODE仅接受full、netloc、netloc-tag三个值否则回退到DEFAULT_URL_RENDER_MODE fullviews.py。为什么默认禁用 faviconBukuserver 默认禁用 favicon目的是阻止任何非用户触发的网络活动。其 favicon 由 Google 的 favicon 服务协助生成见 views.py 中http://www.google.com/s2/favicons?domain{netloc}的调用。社区研究指出favicon 可能被用于浏览器指纹追踪fingerprinting例如GitHub 上的 supercookie 示例项目jonasstrehle/supercookie伊利诺伊大学芝加哥分校UIC科学家的相关论文2021 年 Heise Online 的报道附英文翻译。即 favicon 存在被用作超级 Cookie追踪用户浏览习惯的潜在风险。因此项目默认将其关闭如你确实需要展示网站图标可通过BUKUSERVER_DISABLE_FAVICONfalse重新开启。RESTful API 接口Bukuserver 实现了 RESTful API为 Buku 的核心功能提供 HTTP 接口。API 根路径为/api可在/apidocs端点访问基于 Swagger 的交互式文档例如http://localhost:5000/apidocs。Swagger 配置与 YAML 定义文件位于 bukuserver/apidocs/服务端通过Swagger(app, template_file...template.yml)挂载server.py。注意与固定不变的 ID 不同API 中的 index索引并非静态的——执行删除等操作后索引可能变化因此基于 URL 搜索获得当前索引后再操作是更稳妥的用法。API 端点总览端点支持方法功能/api/tagsGET获取全部标签列表/api/tags/{tag}GET、DELETE、PUT查询指定标签信息从所有书签中删除或替换为新标签/api/bookmarksGET、DELETE、POST获取/清空全部书签创建新书签/api/bookmarks/{index}GET、DELETE、PUT获取、删除或更新单条书签/api/bookmarks/{start_index}/{end_index}GET、DELETE、PUT按索引区间批量获取、删除或更新书签/api/bookmarks/searchGET、DELETE获取/删除匹配查询的书签可借此通过 URL 反查当前索引/api/bookmarks/{index}/tinyGET获取缩短 URL已废弃/api/bookmarks/{index}/refreshPOST远程抓取并解析 URL更新单条书签数据/api/bookmarks/refreshPOST远程抓取并解析所有书签的 URL/api/fetch_dataPOST对任意 URL 调用抓取解析功能/api/network_handlePOST对任意 URL 调用抓取解析功能旧版接口补充说明/api/bookmarks/{index}/tiny已废弃——因为提供该服务的 tny.im 已不再可用目前该端点返回Response.REMOVED()见 api.py。/api/bookmarks/reorder也是可用端点POST通过bdb.reorder(...)批量重排书签顺序。JSON 与 urlencoded 请求格式说明需要特别留意部分POST/DELETE端点书签搜索、数据抓取期望参数以 urlencoded 格式提交其余端点期望 JSON 格式。以书签搜索为例apidocs/bookmarks_search/get.ymlGET /api/bookmarks/search支持以下查询参数all_keywords布尔值多个关键词时排除部分匹配deep布尔值若为 false默认只匹配完整单词regex布尔值关键词按正则处理会覆盖其他选项order数组控制排序格式如[-netloc, title, url]合法字段有index、url(或uri)、title、description(或desc)、tags、netloc字段前可加/-指定方向markers布尔值启用后按前缀把关键词限定到特定字段——.匹配标题、匹配描述、:匹配 URL、#匹配标签逗号分隔、部分匹配不受deep影响、#,只匹配完整标签、*匹配全部字段keywords必填数组待搜索的术语集。另外两个特殊组合当all_keywordstrue、regexfalse且keywords为空时匹配无标题或无标签的书签当keywords为immutable时匹配用--immutable标记的书签。接口背后的实现机制API 路由由 server.py 的add_url_rule统一注册视图实现集中在 api.py。几个值得关注的点统一响应封装所有端点返回结构化响应对象通过 response.py 提供SUCCESS、FAILURE、BOOKMARK_NOT_FOUND、TAG_NOT_FOUND、RANGE_NOT_VALID等预定义响应便于客户端判断结果。书签实体结构GET返回的书签对象包含index可选、url、title、tags、description字段见entity()api.py。搜索结果模式下会额外附带index方便反查。标签校验/api/tags/{tag}中的标签需匹配正则TAG_RE定义于 forms.py非法标签返回TAG_NOT_VALID。远程抓取refresh_bookmark调用bdb.refreshdb(index, threads)完成抓取threads可经表单参数指定默认 4fetch_data与network_handle均调用buku.fetch_data()区别仅在返回字段的裁剪方式——fetch_data返回 NamedTuple 全量字段network_handle只返回标题/描述/标签/识别 MIME/坏 URL 标记。Bookmarklet 支持GET /bookmarklet实现于bookmarklet_redirect会根据传入的url、title、description、tags、fetch参数将已存在/新书签重定向到对应的编辑或创建页并携带popupTrue以弹出窗口形式操作配套的拖拽小书签脚本见 bookmarklet.js。界面与统计Bukuserver 的 GUI 基于 Flask-Admin 构建在 server.py 中注册了三个管理视图views.pyBookmarks书签列表、创建、编辑、详情、删除支持popup弹窗表单对应 templates/bukuserver/ 下的bookmark_create_modal.html、bookmark_edit_modal.html、bookmark_details_modal.html等Tags标签按使用次数排序展示全部标签支持重命名、删除、批量刷新缓存60 秒自动刷新Statistic统计基于全部书签统计热门域名netloc、标签与标题词频并以 Chart.js 图表呈现数据来自 views.py 的StatisticView页面模板为statistic.html。界面外观通过BUKUSERVER_THEME切换基于 Bootswatch 4 主题slate是暗色模式的推荐选择主题以 swatch 形式传入Bootstrap4Theme。若安装了[locales]扩展还可通过BUKUSERVER_LOCALE切换界面语言仓库的 bukuserver/translations/ 目录内含 de、fr、ru 等多语言编译文件属于部分支持。本指南侧重于部署、配置与 API 的可操作细节不同主题default与slate的完整界面截图可参考项目 wiki 的 Bukuserver 页面那里收录了首页、书签统计、启用了 favicon 与netloc-tag渲染模式的书签页、slate 主题书签页、新建/编辑书签、书签详情、标签页以及交互式 API 文档等大量界面演示。赞分享开发工具【免费下载链接】buku:bookmark: Personal mini-web in text项目地址https://gitcode.com/gh_mirrors/bu/buku点击查看免费下载相关推荐bukuserver-runner 完全指南Buku 书签 Web 服务运行器与多数据库切换实战bukuserver runner 完全指南Buku 书签 Web 服务运行器与多数据库切换实战 bukuserver runner 是 Buku 项目中负责开发工具buku命令行书签管理器的完整实战指南buku命令行书签管理器的完整实战指南 buku 是一款强大的命令行书签管理器作者将其定位为个人文本版迷你网络personal mini web in开发工具告别摄像头混乱OpenMV IDE如何让多设备开发变得简单直观告别摄像头混乱OpenMV IDE如何让多设备开发变得简单直观 你是否曾经遇到过这样的困扰当你同时连接多个OpenMV摄像头进行开发时面对设备列表中一串串开发工具IDE嵌入式上一篇Apache BRPC中的RDMA支持深度解析下一篇图神经网络入门GNN基础理论与实际应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考