尧图网页设计 
Tabby 离线环境 Docker 部署完全指南内网无互联网场景下的模型镜像构建与运行【免费下载链接】tabbySelf-hosted AI coding assistant项目地址: https://gitcode.com/GitHub_Trending/tab/tabby本文围绕自托管 AI 编程助手 Tabby 在无互联网air-gapped环境下的 Docker 部署展开先在联网机器上构建一个内置模型的 Docker 镜像再通过 tar 包将镜像传输到离线机器上加载运行全程无需任何外网访问。读完本文你将掌握离线部署的核心流程、TABBY_MODEL_CACHE_ROOT等关键环境变量的作用机制以及tabby-cpu download与serve命令的完整用法并能结合仓库源码理解模型下载与目录组织的内在原理。离线部署的整体思路Tabby 是一个需要加载本地大语言模型如代码补全模型、Embedding 模型才能提供服务的自托管应用。在联网环境下Tabby 首次启动serve时会自动从模型注册表下载所需模型而在完全断网的内网air-gapped环境中这一过程无法完成因此必须换一种思路在有互联网的计算机上基于官方镜像构建一个已经包含所需模型的 Docker 镜像将构建好的镜像通过docker save导出为 tar 文件拷贝到离线机器在离线机器上通过docker load加载镜像并运行容器Tabby 即可完全脱离外网对外提供补全服务。整个过程只需要离线机器上装有 Docker不需要任何网络连接。前置条件需求说明联网计算机安装 Docker用于构建并导出包含模型的镜像离线计算机安装 Docker用于加载并运行镜像传输介质U 盘、移动硬盘或内部网络用于拷贝 tar 镜像文件第一步编写 Dockerfile 预置模型在有互联网的计算机上新建一个Dockerfile内容如下FROM tabbyml/tabby ENV TABBY_MODEL_CACHE_ROOT/models RUN /opt/tabby/bin/tabby-cpu download --model StarCoder-1B RUN /opt/tabby/bin/tabby-cpu download --model Nomic-Embed-Text这个 Dockerfile 完成三件事FROM tabbyml/tabby以官方 Tabby 镜像为基础。官方镜像的入口是/opt/tabby/bin/tabby见 docker/Dockerfile.cuda 与 docker/Dockerfile.rocm同时为了兼容历史 CPU 构建镜像内还提供了一个与主程序等价的可执行文件tabby-cpu由cp /opt/tabby/bin/tabby /opt/tabby/bin/tabby-cpu生成。正是这个tabby-cpu让我们可以在构建阶段直接调用下载命令。ENV TABBY_MODEL_CACHE_ROOT/models设置模型缓存根目录。在构建过程中下载的模型文件会被保存到容器内的/models目录从而固化进镜像层。两条RUN指令分别下载代码补全模型StarCoder-1B和 Embedding 模型Nomic-Embed-Text。Embedding 模型用于仓库级代码搜索与索引是 Tabby 提供仓库上下文补全RAG能力的基础。TABBY_MODEL_CACHE_ROOT的原理从源码看TABBY_MODEL_CACHE_ROOT环境变量直接决定了模型文件的存放位置。在 crates/tabby-common/src/path.rs 中该环境变量被解析为TABBY_MODEL_CACHE_ROOT静态变量models_dir()函数优先返回它指定的路径否则回退到TABBY_ROOT/modelspath.rspub fn models_dir() - PathBuf { if let Some(cache_root) *TABBY_MODEL_CACHE_ROOT { cache_root.clone() } else { tabby_root().join(models) } }因此在构建镜像时设置ENV TABBY_MODEL_CACHE_ROOT/models等于把模型缓存根目录整体搬进了镜像层。运行时若不覆盖该变量容器内依然会优先从/models读取模型实现完全离线加载。download子命令与模型注册表download是 Tabby CLI 的子命令之一。入口定义在 crates/tabby/src/main.rs支持serve与download两个子命令download的参数解析见 crates/tabby/src/download.rs--model要下载的模型 ID如StarCoder-1B--prefer-local-file若本地已有文件则跳过远程校验默认false。下载的核心实现位于 crates/tabby-download/src/lib.rs。其内部逻辑值得关注模型注册表Tabby 通过ModelRegistry从远程获取模型元信息models.json包含下载 URL、SHA256 校验和、提示词模板等见 crates/tabby-common/src/registry.rs。parse_model_id会把StarCoder-1B解析为TabbyML/StarCoder-1B即默认从TabbyML组织下载SHA256 完整性校验下载前会对已存在文件做HashChecker校验校验和不一致会触发重新下载lib.rs断点容错与重试下载使用带 jitter 的指数退避策略ExponentialBackoff::from_millis(100).map(jitter).take(2)并通过.tmp中间文件 完成后rename的方式避免产生半成品文件lib.rs下载地址可定制可通过TABBY_DOWNLOAD_HOST切换下载主机默认huggingface.co或通过TABBY_HUGGINGFACE_HOST_OVERRIDE将 HuggingFace 地址替换为镜像站如modelscope.co这些逻辑在filter_download_address中实现并有完整的单元测试覆盖lib.rs。这意味着即便在联网机器上下载模型时网络受限也可以通过设置镜像主机变量来完成模型获取。第二步构建包含模型的 Docker 镜像docker build -t tabby-offline .docker build会逐条执行 Dockerfile先拉取官方 Tabby 镜像再在构建阶段调用tabby-cpu download把两个模型下载并写入/models目录。由于模型文件已经进入镜像层最终镜像体积会比官方基础镜像大不少取决于所选模型的大小请确保磁盘空间充足。第三步将镜像导出为 tar 文件docker save -o tabby-offline.tar tabby-offlinedocker save将本地镜像序列化为单一 tar 归档文件便于拷贝和离线传输。tar 文件的大小与镜像体积一致即包含模型权重务必确认目标传输介质的剩余空间。第四步拷贝到离线计算机将tabby-offline.tar通过 U 盘、移动硬盘或内网文件传输等方式拷贝到没有互联网的计算机上。这是唯一一次物理传输之后离线机器上的所有操作都不再需要网络。第五步从 tar 文件加载镜像docker load -i tabby-offline.tardocker load会把 tar 归档还原为 Docker 镜像。加载完成后可以用docker images确认tabby-offline镜像已经存在。第六步运行 Tabby 容器docker run -it \ --gpus all -p 8080:8080 -v $HOME/.tabby:/data \ tabby-offline \ serve --model StarCoder-1B --device cuda逐项拆解这条命令参数作用-it以交互模式运行便于在前台观察 CLI 输出--gpus all将宿主机全部 GPU 暴露给容器CPU 环境可去掉-p 8080:8080将容器内 8080 端口映射到宿主机供 IDE 插件连接-v $HOME/.tabby:/data挂载数据卷持久化 Tabby 数据serve --model StarCoder-1B --device cuda启动服务并指定补全模型与推理设备serve命令的关键参数serve子命令的参数定义在 crates/tabby/src/serve.rs--model用于/v1/completions接口的补全模型 ID--chat-model用于/v1/chat/completions的对话模型 ID可选--host监听地址默认0.0.0.0--port监听端口默认8080--device推理设备可选cpu、cuda、rocm、metal、vulkan见 crates/tabby/src/main.rs 的Device枚举默认cpu--parallelism模型服务并行度提高该值会显著增加 GPU 显存占用默认1。serve启动时会调用load_modelserve.rs检查本地是否已有补全模型、对话模型与 Embedding 模型缺少则自动触发下载。由于我们构建的镜像已在/models中预置了模型离线环境下这一步会直接命中本地缓存而无需联网。关于挂载目录/data官方镜像的入口设置为ENTRYPOINT [/opt/tabby/bin/tabby]并定义了ENV TABBY_ROOT/data见 docker/Dockerfile.cuda。Tabby 的运行时根目录由TABBY_ROOT控制默认是~/.tabby见 crates/tabby-common/src/path.rs。因此-v $HOME/.tabby:/data实际上把宿主机上的 Tabby 数据目录与容器内的/data即TABBY_ROOT绑定让仓库索引、事件日志、配置等数据在容器重建后依然保留在宿主机上。注意由于镜像内已设置TABBY_MODEL_CACHE_ROOT/models模型文件位于镜像层而非数据卷中这是离线方案的关键设计。容器成功启动后你会看到类似下图的 CLI 输出服务地址、端口与模型加载信息部署后的验证容器运行起来后可通过以下方式确认服务正常curl http://localhost:8080/v1/health/v1/health路由在 crates/tabby/src/serve.rs 中注册返回服务健康状态。随后即可在 VSCode、Vim、IntelliJ 等编辑器插件中把 Tabby 服务地址配置为离线机器的http://ip:8080开始使用离线代码补全。常见问题与排查要点镜像体积过大模型权重全部打包进镜像导致体积较大这是离线方案不可避免的代价可考虑只预置实际使用的模型如仅StarCoder-1B来减小体积。GPU 不可用如果离线机器没有 GPU去掉--gpus all并将--device改为cpu运行。模型校验失败download阶段会对模型文件做 SHA256 校验见 crates/tabby-download/src/lib.rs联网构建时应确保网络稳定避免下载不完整。传输中断tar 文件较大时建议先校验拷贝完整性如 md5sum再进行docker load。端口冲突若离线机器 8080 已被占用可改用-p 8081:8080同时更新编辑器插件中的服务地址。小结通过联网构建镜像 → 导出 tar → 离线加载运行三步走Tabby 可以完整部署在无互联网的内网环境中。其关键在于利用TABBY_MODEL_CACHE_ROOT将模型缓存固化进镜像层配合tabby-cpu download在构建阶段预下载模型最终让serve启动时无需任何网络请求即可加载全部模型权重为离线办公网络提供自托管的 AI 编程辅助能力。【免费下载链接】tabbySelf-hosted AI coding assistant项目地址: https://gitcode.com/GitHub_Trending/tab/tabby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Tabby 离线环境 Docker 部署完全指南：内网无互联网场景下的模型镜像构建与运行
Tabby 离线环境 Docker 部署完全指南内网无互联网场景下的模型镜像构建与运行【免费下载链接】tabbySelf-hosted AI coding assistant项目地址: https://gitcode.com/GitHub_Trending/tab/tabby本文围绕自托管 AI 编程助手 Tabby 在无互联网air-gapped环境下的 Docker 部署展开先在联网机器上构建一个内置模型的 Docker 镜像再通过 tar 包将镜像传输到离线机器上加载运行全程无需任何外网访问。读完本文你将掌握离线部署的核心流程、TABBY_MODEL_CACHE_ROOT等关键环境变量的作用机制以及tabby-cpu download与serve命令的完整用法并能结合仓库源码理解模型下载与目录组织的内在原理。离线部署的整体思路Tabby 是一个需要加载本地大语言模型如代码补全模型、Embedding 模型才能提供服务的自托管应用。在联网环境下Tabby 首次启动serve时会自动从模型注册表下载所需模型而在完全断网的内网air-gapped环境中这一过程无法完成因此必须换一种思路在有互联网的计算机上基于官方镜像构建一个已经包含所需模型的 Docker 镜像将构建好的镜像通过docker save导出为 tar 文件拷贝到离线机器在离线机器上通过docker load加载镜像并运行容器Tabby 即可完全脱离外网对外提供补全服务。整个过程只需要离线机器上装有 Docker不需要任何网络连接。前置条件需求说明联网计算机安装 Docker用于构建并导出包含模型的镜像离线计算机安装 Docker用于加载并运行镜像传输介质U 盘、移动硬盘或内部网络用于拷贝 tar 镜像文件第一步编写 Dockerfile 预置模型在有互联网的计算机上新建一个Dockerfile内容如下FROM tabbyml/tabby ENV TABBY_MODEL_CACHE_ROOT/models RUN /opt/tabby/bin/tabby-cpu download --model StarCoder-1B RUN /opt/tabby/bin/tabby-cpu download --model Nomic-Embed-Text这个 Dockerfile 完成三件事FROM tabbyml/tabby以官方 Tabby 镜像为基础。官方镜像的入口是/opt/tabby/bin/tabby见 docker/Dockerfile.cuda 与 docker/Dockerfile.rocm同时为了兼容历史 CPU 构建镜像内还提供了一个与主程序等价的可执行文件tabby-cpu由cp /opt/tabby/bin/tabby /opt/tabby/bin/tabby-cpu生成。正是这个tabby-cpu让我们可以在构建阶段直接调用下载命令。ENV TABBY_MODEL_CACHE_ROOT/models设置模型缓存根目录。在构建过程中下载的模型文件会被保存到容器内的/models目录从而固化进镜像层。两条RUN指令分别下载代码补全模型StarCoder-1B和 Embedding 模型Nomic-Embed-Text。Embedding 模型用于仓库级代码搜索与索引是 Tabby 提供仓库上下文补全RAG能力的基础。TABBY_MODEL_CACHE_ROOT的原理从源码看TABBY_MODEL_CACHE_ROOT环境变量直接决定了模型文件的存放位置。在 crates/tabby-common/src/path.rs 中该环境变量被解析为TABBY_MODEL_CACHE_ROOT静态变量models_dir()函数优先返回它指定的路径否则回退到TABBY_ROOT/modelspath.rspub fn models_dir() - PathBuf { if let Some(cache_root) *TABBY_MODEL_CACHE_ROOT { cache_root.clone() } else { tabby_root().join(models) } }因此在构建镜像时设置ENV TABBY_MODEL_CACHE_ROOT/models等于把模型缓存根目录整体搬进了镜像层。运行时若不覆盖该变量容器内依然会优先从/models读取模型实现完全离线加载。download子命令与模型注册表download是 Tabby CLI 的子命令之一。入口定义在 crates/tabby/src/main.rs支持serve与download两个子命令download的参数解析见 crates/tabby/src/download.rs--model要下载的模型 ID如StarCoder-1B--prefer-local-file若本地已有文件则跳过远程校验默认false。下载的核心实现位于 crates/tabby-download/src/lib.rs。其内部逻辑值得关注模型注册表Tabby 通过ModelRegistry从远程获取模型元信息models.json包含下载 URL、SHA256 校验和、提示词模板等见 crates/tabby-common/src/registry.rs。parse_model_id会把StarCoder-1B解析为TabbyML/StarCoder-1B即默认从TabbyML组织下载SHA256 完整性校验下载前会对已存在文件做HashChecker校验校验和不一致会触发重新下载lib.rs断点容错与重试下载使用带 jitter 的指数退避策略ExponentialBackoff::from_millis(100).map(jitter).take(2)并通过.tmp中间文件 完成后rename的方式避免产生半成品文件lib.rs下载地址可定制可通过TABBY_DOWNLOAD_HOST切换下载主机默认huggingface.co或通过TABBY_HUGGINGFACE_HOST_OVERRIDE将 HuggingFace 地址替换为镜像站如modelscope.co这些逻辑在filter_download_address中实现并有完整的单元测试覆盖lib.rs。这意味着即便在联网机器上下载模型时网络受限也可以通过设置镜像主机变量来完成模型获取。第二步构建包含模型的 Docker 镜像docker build -t tabby-offline .docker build会逐条执行 Dockerfile先拉取官方 Tabby 镜像再在构建阶段调用tabby-cpu download把两个模型下载并写入/models目录。由于模型文件已经进入镜像层最终镜像体积会比官方基础镜像大不少取决于所选模型的大小请确保磁盘空间充足。第三步将镜像导出为 tar 文件docker save -o tabby-offline.tar tabby-offlinedocker save将本地镜像序列化为单一 tar 归档文件便于拷贝和离线传输。tar 文件的大小与镜像体积一致即包含模型权重务必确认目标传输介质的剩余空间。第四步拷贝到离线计算机将tabby-offline.tar通过 U 盘、移动硬盘或内网文件传输等方式拷贝到没有互联网的计算机上。这是唯一一次物理传输之后离线机器上的所有操作都不再需要网络。第五步从 tar 文件加载镜像docker load -i tabby-offline.tardocker load会把 tar 归档还原为 Docker 镜像。加载完成后可以用docker images确认tabby-offline镜像已经存在。第六步运行 Tabby 容器docker run -it \ --gpus all -p 8080:8080 -v $HOME/.tabby:/data \ tabby-offline \ serve --model StarCoder-1B --device cuda逐项拆解这条命令参数作用-it以交互模式运行便于在前台观察 CLI 输出--gpus all将宿主机全部 GPU 暴露给容器CPU 环境可去掉-p 8080:8080将容器内 8080 端口映射到宿主机供 IDE 插件连接-v $HOME/.tabby:/data挂载数据卷持久化 Tabby 数据serve --model StarCoder-1B --device cuda启动服务并指定补全模型与推理设备serve命令的关键参数serve子命令的参数定义在 crates/tabby/src/serve.rs--model用于/v1/completions接口的补全模型 ID--chat-model用于/v1/chat/completions的对话模型 ID可选--host监听地址默认0.0.0.0--port监听端口默认8080--device推理设备可选cpu、cuda、rocm、metal、vulkan见 crates/tabby/src/main.rs 的Device枚举默认cpu--parallelism模型服务并行度提高该值会显著增加 GPU 显存占用默认1。serve启动时会调用load_modelserve.rs检查本地是否已有补全模型、对话模型与 Embedding 模型缺少则自动触发下载。由于我们构建的镜像已在/models中预置了模型离线环境下这一步会直接命中本地缓存而无需联网。关于挂载目录/data官方镜像的入口设置为ENTRYPOINT [/opt/tabby/bin/tabby]并定义了ENV TABBY_ROOT/data见 docker/Dockerfile.cuda。Tabby 的运行时根目录由TABBY_ROOT控制默认是~/.tabby见 crates/tabby-common/src/path.rs。因此-v $HOME/.tabby:/data实际上把宿主机上的 Tabby 数据目录与容器内的/data即TABBY_ROOT绑定让仓库索引、事件日志、配置等数据在容器重建后依然保留在宿主机上。注意由于镜像内已设置TABBY_MODEL_CACHE_ROOT/models模型文件位于镜像层而非数据卷中这是离线方案的关键设计。容器成功启动后你会看到类似下图的 CLI 输出服务地址、端口与模型加载信息部署后的验证容器运行起来后可通过以下方式确认服务正常curl http://localhost:8080/v1/health/v1/health路由在 crates/tabby/src/serve.rs 中注册返回服务健康状态。随后即可在 VSCode、Vim、IntelliJ 等编辑器插件中把 Tabby 服务地址配置为离线机器的http://ip:8080开始使用离线代码补全。常见问题与排查要点镜像体积过大模型权重全部打包进镜像导致体积较大这是离线方案不可避免的代价可考虑只预置实际使用的模型如仅StarCoder-1B来减小体积。GPU 不可用如果离线机器没有 GPU去掉--gpus all并将--device改为cpu运行。模型校验失败download阶段会对模型文件做 SHA256 校验见 crates/tabby-download/src/lib.rs联网构建时应确保网络稳定避免下载不完整。传输中断tar 文件较大时建议先校验拷贝完整性如 md5sum再进行docker load。端口冲突若离线机器 8080 已被占用可改用-p 8081:8080同时更新编辑器插件中的服务地址。小结通过联网构建镜像 → 导出 tar → 离线加载运行三步走Tabby 可以完整部署在无互联网的内网环境中。其关键在于利用TABBY_MODEL_CACHE_ROOT将模型缓存固化进镜像层配合tabby-cpu download在构建阶段预下载模型最终让serve启动时无需任何网络请求即可加载全部模型权重为离线办公网络提供自托管的 AI 编程辅助能力。【免费下载链接】tabbySelf-hosted AI coding assistant项目地址: https://gitcode.com/GitHub_Trending/tab/tabby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考