LocalAI 文档网站本地构建运行指南Hugo 模块、Docker Compose 与常见问题排查【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI本文聚焦 LocalAI 项目自身的文档网站docs 目录如何在本地构建与运行。你将掌握两类工作流一是用make docs或hugo server直接驱动静态站点热更新二是通过docker-compose在容器中以 1313 端口运行站点并挂载源码实时刷新同时会深入 Hugo 配置、Makefile 构建链与两类高频报错的根因排查适合需要为 LocalAI 编写、调试或发布文档的贡献者与运维人员。文档站的整体定位与目录构成LocalAI 仓库中的 docs 目录 并不是普通资料夹而是一个独立的 Hugo 站点。按仓库根目录 Makefile 中Documentation and website一节的注释说明发布站点由两个 Hugo 站点组成根路径由 website 站承担文档则嵌套挂在/docs/路径下。编辑时两者分开启动make docs/make website上线时通过make site合并两个站点的构建产物含旧版 URL 跳转供 GitHub Pages 等平台部署。文档站的核心文件与职责如下路径作用docs/hugo.tomlHugo 站点配置主题、语言、输出格式、模块挂载docs/content/文档正文overview、getting-started、features、advanced、operations、reference、faq 等分节docs/layouts/页面模板含_default与 gallery 页面布局docs/static/静态资源与生成的gallery.htmldocs/go.modHugo 模块声明module github.com/mudler/LocalAI/docs要求 Go 1.19docs/Dockerfile、docs/docker-compose.yaml容器化运行文档站docs/netlify.tomlCINetlify构建环境Hugo 0.146.3、Go 1.22.2值得注意的是docs/hugo.toml 中声明的主题是hugo-theme-relearndark/blue 风格的zen-dark与neon变体均来自该主题而 docs/README.md 中Requirement一节对 Google Docsy 模块图的描述属于该文档沿用的历史说明。本地构建与站点渲染以 hugo.toml 的实际配置为准——README 中有关 Docsy 模块依赖的细节可理解为该项目曾用 Hugo 模块方式拉取主题依赖这一机制的佐证。运行前置条件按 docs/README.md 的要求本地构建需要一个较新的 Hugoextended版本必须带扩展版原因见后文问题排查中 TOCSS 报错一节。除此之外结合仓库配置还可归纳出三组依赖Hugo extended站点构建与 SCSS 编译都需要它Go 工具链构建期间 Hugo 需要解析模块见 docs/go.mod生产构建环境在 docs/netlify.toml 中固定为HUGO_VERSION 0.146.3、GO_VERSION 1.22.2本地可用近似版本Node/npm PostCSS只有当你要修改 SCSS 并希望改动生效发布时才需要安装。根因是 docs/package.json 的devDependencies中声明了autoprefixer、postcss、postcss-cli用于主题样式管线的自动前缀处理安装命令为npm install纯内容编辑修改 Markdown不涉及 SCSS可以跳过这一步。方案一本地直接构建与热更新官方推荐从仓库根目录出发使用 Makefile 封装好的目标make docs查看 Makefile 可以确认该目标并非简单调用 Hugo而是自带依赖链docs/static/gallery.html: docs/layouts/_default $(GOCMD) run ./.github/ci/modelslist.go ./gallery/index.yaml docs/static/gallery.html .PHONY: docs docs: docs/static/gallery.html cd docs hugo serve也就是说make docs会先用 Go 运行生成器把仓库根目录 gallery/index.yaml 的模型清单渲染成 docs/static/gallery.html模型 Gallery 页面再进入 docs 目录执行hugo serve。因此如果直接运行hugo而 Gallery 页缺失或过期需要先手动补齐该生成步骤。如果你已进入 docs 目录、想跳过 Makefile 直接驱动 Hugo也可以等价地运行cd docs hugo serverhugo server是 Hugo 的开发服务器监听本地端口、监听文档文件变化并即时重编译保存.md后浏览器刷新即可看到内容更新。需要注意的是cd docs与make docs的区别只在于前者少了 gallery.html 预生成这一步两者最终都执行同一套hugo serve流程。方案二容器内运行免本地安装依赖如果本机不想安装 Hugo、Go 等工具链仓库提供了完整的容器方案全程只需 Docker。先看镜像定义 docs/DockerfileFROM klakegg/hugo:ext-alpine RUN apk add git \ git config --global --add safe.directory /src基础镜像选用klakegg/hugo:ext-alpine——即 Hugo 的extendedAlpine 变体镜像内额外安装了git并把/src标记为安全目录以满足 Hugo 模块与 git 信息enableGitInfo的需要。编排文件 docs/docker-compose.yaml 提供了服务定义version: 3.3 services: site: image: docsy/docsy-example build: context: . command: server ports: - 1313:1313 volumes: - .:/src按 docs/README.md 的操作步骤# 1. 构建镜像 docker-compose build # 2. 运行容器 docker-compose up也可以一条命令同时完成构建与启动docker-compose up --build验证服务是否可用在浏览器地址栏访问http://localhost:1313。容器以command: server进入 Hugo server 模式并通过 volume 把当前目录挂载到/src因此你修改源码后保存改动会立即反映到浏览器页面与本地hugo server相同的热更新体验。清理停止容器只需在终端按Ctrl C如需进一步删除构建产生的镜像执行docker-compose rm问题排查两类高频启动报错文档站运行在本地时docs/README.md 给出了两个典型的失败场景及其根因。报错一TOCSS: failed to transform scss/main.scss错误特征如下➜ hugo server INFO 2021/01/21 21:07:55 Using config file: Building sites … INFO 2021/01/21 21:07:55 syncing static files to / Built in 288 ms Error: Error building site: TOCSS: failed to transform scss/main.scss (text/x-scss): resource scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68 not found in file cache根因你的 Hugo 是普通版standard而站点主题的样式使用 SCSS 编译管线Hugo 的 TOCSS 能力仅存在于extended版本中。解决方案是卸载后用 Hugoextended版本替换重新执行构建即可。仓库的容器方案在 docs/Dockerfile 中刻意选用hugo:ext-alpine正是为了避免这个坑。报错二failed to download modules: binary with name go not found错误特征如下➜ hugo server Error: failed to download modules: binary with name go not found根因Hugo 在构建时按 docs/hugo.toml 的[module]配置解析模块把content、static、layouts、data、assets等目录挂载进站点解析远程主题模块依赖需要 Go 二进制参与而当前系统没有安装 Go。解决方案是安装 Go 语言工具链后重试若你的改动不涉及主题模块下载但机器上长期没有 Go也可以考虑直接使用本文的容器方案镜像内已内置所需运行时。深入从配置读懂文档站的构建链路了解常见报错后再结合 docs/hugo.toml 逐项看构建参数能显著提高排障效率。路径与语言。站点固定baseURL https://localai.io/docs/——如文件头部注释所述文档站是营销站website之下的二级 Hugo 站点统一挂在/docs/前缀CI 会用--baseURL传入相同路径保证本地构建与线上产物链接一致。默认语言为英文en-GB站点标题为 LocalAI。输出格式。[outputs]配置指明首页输出html、rss、print、search四种格式章节与普通页面输出html、rss、print。其中print对应 Hugo Relearn 主题的整节打印/导出为单页能力search是站内搜索索引。Markdown 渲染。使用 Goldmark 渲染器并打开了两项关键开关[markup.goldmark.renderer] unsafe true [markup.goldmark.parser.attribute] block true title trueunsafe true允许在 Markdown 中嵌入原始 HTMLparser.attribute允许在块级元素与标题上书写属性如锚点与样式类这是 Relearn 主题大量语法特性的基础。模块挂载。[module.mounts]把本地目录映射进 Hugo 的虚拟文件系统[[module.mounts]] source content target content [[module.mounts]] source ../images target static/images即文档站点会从content/、static/、layouts/、data/、assets/、i18n/读取内容并把仓库根目录的images映射为站点静态图片目录。这部分正是文档在Requirement一节中提及 Hugo 模块依赖机制的落点。内容组织。站点正文从 docs/content/_index.md 展开。文档主体可粗分为安装运行getting-started、能力特性features、进阶配置advanced、运维治理operations、参考手册reference与 FAQ 等板块正文里大量使用{{% relref ... %}}短代码做内部引用保证跨站点路径在渲染后仍然有效。编辑新文档时沿用这套相对引用写法即可。发布链路。上线构建由 Makefile 的site目标统一完成site: docs/static/gallery.html rm -rf website/public docs/public cd website hugo --minify --baseURL $(SITE_BASE_URL)/ cd docs hugo --minify --baseURL $(SITE_BASE_URL)/docs/ mkdir -p website/public/docs它先分别以--minify压缩构建两个站点再把 docs 构建产物并入website/public/docs形成最终可部署的合并树CI 端docs/netlify.toml则固定了 Hugo 与 Go 的精确版本以保证构建可复现。小结一套工作流定位问题把上文串起来实际工作中最常用的判断路径是只改正文 Markdown→ 依赖已就绪时直接cd docs hugo server或用make docs额外刷新 Gallery 页改主题/SCSS→ 先npm install准备 PostCSS 管线并确认用的是 Hugo extended不想装环境或报go/TOCSS 错误→ 在 docs 目录执行docker-compose up --build访问http://localhost:1313要发版→ 走根目录make site可选SITE_BASE_URL覆盖默认的http://localhost:8000产出合并后的发布目录。理解 Makefile 中gallery.html生成、hugo serve启动与--minify发布这三层动作以及 docs/hugo.toml 中模块挂载与 Markdown 渲染开关即可对 LocalAI 文档站的本地编辑、容器运行与 CI 发布拥有完整、可排障的认知。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
