企业官网建设流程全解析

1. 为什么我要在本地折腾一个 AI 编程助手

第一次听说 Codex 能本地跑的时候，我其实是持怀疑态度的。毕竟过去两年，我试过的绝大多数 AI 编程工具都是云端方案——响应快、模型强，但有两个问题始终绕不开：一是代码隐私，公司内部项目根本不敢往云端传；二是网络抖动，赶上高峰期延迟能飙到十几秒，补全一个函数等得人想砸键盘。直到我在几个开源社区看到有人把 Codex 跑在本地 Docker 里，配合本地大模型做推理，才意识到这条路是真的能走通的。

Codex 本质上是一个 AI 编程助手的客户端框架，它负责把你的代码上下文、编辑指令、对话历史打包成模型能理解的请求，再把模型返回的结果解析成可用的代码补全、重构建议或者解释说明。它本身不绑定某个特定模型，你可以把它理解成一个"翻译官"——左边连着你的编辑器，右边连着任意一个兼容接口的大模型服务。这个特性决定了它天然适合本地部署：模型跑在你自己的机器上，Codex 只做协议转换和交互层，数据不出内网。

那本地部署到底解决了什么问题？我总结下来是三个：数据主权、响应确定性、成本可控。数据主权不用多说，代码是公司的核心资产，能不出本机就不出本机。响应确定性指的是没有网络波动，本地推理延迟稳定在几百毫秒到几秒之间，取决于你的显卡。成本可控则是长期账——云端 API 按 token 计费，重度使用一个月几百块很正常，而本地部署一次性投入硬件之后，边际成本几乎为零。

这篇文章适合谁看？如果你是有一定命令行基础的后端或全栈开发者，想给自己搭一个不依赖外部服务的编程助手，那这篇内容就是为你写的。如果你完全没碰过 Docker，也没关系，我会把每一步拆到能直接复制粘贴的程度。但我要提前说清楚：本地部署不是一键安装包，中间会遇到显卡驱动、容器网络、模型加载各种坑，你得有折腾的心理准备。

2. 部署前的整体设计与选型思路

2.1 为什么选 Docker 而不是裸机安装

Codex 的官方安装方式其实有两种：一种是直接在本机装二进制包，另一种是走 Docker 容器。我两种都试过，最后坚定地选了 Docker，原因有三个。

第一是依赖隔离。Codex 运行时会依赖特定版本的 Node.js、Python 运行时以及一些系统库。如果你本机已经装了其他项目需要的不同版本，裸机安装很容易出现版本冲突。我有个朋友就是本机 Node 18 和 Codex 要求的 Node 20 打架，折腾了一下午才搞定。Docker 把所有这些依赖封在容器里，跟宿主机完全隔离，你本机装什么版本都不影响。

第二是环境可复现。Docker 的镜像和 compose 文件就是一份完整的环境说明书。你在这台机器上跑通了，换一台机器只要把 compose 文件拷过去，一条命令就能拉起一模一样的环境。这对团队协作特别有用——不用再写"在我机器上是好的"这种废话。

第三是清理方便。本地部署最怕的就是装了一堆东西最后不用了，卸载还卸不干净。Docker 的好处是，不想要了直接docker compose down -v，容器、网络、卷全部清掉，宿主机干干净净。

当然 Docker 也不是没缺点。最大的问题是GPU 透传。如果你要用显卡加速推理，需要装 NVIDIA Container Toolkit，还得确认驱动版本匹配。这一步是新手最容易卡住的地方，后面我会专门讲。

2.2 模型选型：本地大模型怎么挑

Codex 本身不带模型，你得自己准备一个推理后端。目前本地部署最主流的选择是 Ollama 或者 vLLM，前者适合个人开发者，后者适合有服务器资源的团队。模型方面，DeepSeek 系列、Qwen 系列都是编程能力比较强的选择。

选模型的时候要看三个指标：参数量、量化等级、显存占用。参数量决定能力上限，7B 的模型写简单函数没问题，但复杂重构就力不从心；32B 以上的模型编程能力明显更强，但对显存要求也高。量化等级是在精度和显存之间做权衡，Q4 量化能把显存占用压到 FP16 的四分之一左右，精度损失在编程任务上基本感知不到。

我整理了一个简单的对照表，方便你根据自己的硬件选：

如果你只有一张 8GB 显存的消费级显卡，7B 或 14B 量化版是现实的选择。如果你用的是 Apple Silicon 的 Mac，统一内存架构反而有优势，32GB 内存的 M 系列芯片能跑 14B 甚至 32B 量化模型，速度也还能接受。

2.3 网络与端口规划

本地部署还有一个容易被忽略的点：端口冲突。Codex 默认监听某个端口，Ollama 默认监听 11434，如果你本机还跑着其他服务，很容易撞车。我的习惯是在部署前先用netstat或者lsof查一遍常用端口，把要用的端口规划好写进 compose 文件。

另外，如果你打算让局域网内其他机器也能访问这个 Codex 服务，需要把容器端口映射到0.0.0.0而不是127.0.0.1。但这里有个安全提醒：不要把这个端口直接暴露到公网，本地服务就让它待在本地，需要远程访问的话走内网或者加一层认证。

3. 核心细节解析与实操要点

3.1 Docker 环境准备：别跳过这一步

很多人部署失败，问题都出在 Docker 环境本身没装好。我见过太多人直接docker run然后报一堆错，最后发现是 Docker Desktop 根本没启动成功。

Windows 用户注意，Docker Desktop 依赖 WSL2 或者 Hyper-V。安装的时候如果提示 "virtualization support not detected"，说明你主板的虚拟化技术在 BIOS 里没开。重启进 BIOS，找到 Intel VT-x 或者 AMD-V 选项打开就行。这个坑我踩过，当时以为是软件问题，折腾半天才发现是 BIOS 设置。

装完 Docker Desktop 之后，一定要验证三件事：

# 1. 确认 Docker 守护进程在跑 docker info # 2. 确认能拉取镜像 docker pull hello-world # 3. 确认 compose 插件可用 docker compose version

这三条命令都通过，才说明环境没问题。如果docker info报 "Cannot connect to the Docker daemon"，Windows 上通常是 Docker Desktop 没启动，Linux 上是 docker 服务没起，sudo systemctl start docker即可。

3.2 GPU 支持配置：NVIDIA 用户的必经之路

如果你要用 NVIDIA 显卡加速推理，光装 Docker 还不够，还得装NVIDIA Container Toolkit。这一步的作用是让容器能访问宿主机的 GPU。

Linux 上的安装步骤大致是这样：

# 添加 NVIDIA 容器工具包的软件源 distribution=$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list # 安装并重启 Docker sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker

装完之后用这条命令验证：

docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

如果能看到显卡信息输出，说明 GPU 透传配置成功。如果报错 "could not select device driver"，说明 toolkit 没装好或者 Docker 没重启。

Windows 上的情况稍微复杂一点。Docker Desktop 的 WSL2 后端对 GPU 的支持需要较新版本的驱动，而且不是所有显卡都支持。我的建议是，如果你在 Windows 上折腾 GPU 透传超过一小时还没搞定，先退回到 CPU 推理，把整个流程跑通，再回头解决 GPU 问题。CPU 推理慢是慢，但至少能验证 Codex 本身是能工作的。

3.3 Codex 配置文件的几个关键项

Codex 的配置通常是一个 JSON 或者 TOML 文件，里面有几个参数直接决定它能不能正常工作。

模型接口地址是最关键的。如果你用 Ollama 做后端，地址通常是http://host.docker.internal:11434。注意这里不能用localhost，因为容器里的 localhost 指的是容器自己，不是宿主机。host.docker.internal是 Docker 提供的一个特殊域名，专门用来从容器访问宿主机。Linux 上这个域名默认不生效，需要在 compose 文件里加extra_hosts配置。

模型名称要和你在 Ollama 里拉取的模型名完全一致。比如你ollama pull deepseek-coder:6.7b，配置里就得写deepseek-coder:6.7b，少一个字符都会报模型找不到。

超时时间建议调大一点。本地推理首次加载模型可能要几十秒，默认超时往往不够。我一般设成 120 秒起步，模型大的话设 300 秒。

还有一个容易忽略的配置是context window。Codex 会把你的代码上下文发给模型，上下文越长，模型能理解的代码范围越大，但显存占用也越高。7B 模型建议设 4096 到 8192，32B 模型可以设到 16384。设太大反而会因为显存不足导致推理失败。

4. 完整实操流程：从零到跑通

4.1 第一步：拉起本地模型服务

我以 Ollama 为例，因为它的安装和模型管理最简单。Docker 方式启动 Ollama：

docker run -d \ --name ollama \ --gpus all \ -p 11434:11434 \ -v ollama_data:/root/.ollama \ ollama/ollama

这里-v ollama_data:/root/.ollama是把模型文件持久化到 Docker 卷里，这样容器删了模型不用重新下载。--gpus all是启用 GPU，如果你用 CPU 推理就去掉这个参数。

容器起来之后，进容器拉模型：

docker exec -it ollama ollama pull deepseek-coder:6.7b

下载时间取决于你的网速，6.7B 的量化模型大概 4GB 左右。下载完成后验证一下：

curl http://localhost:11434/api/generate -d '{ "model": "deepseek-coder:6.7b", "prompt": "写一个 Python 快速排序", "stream": false }'

如果返回了排序代码，说明模型服务正常。

4.2 第二步：部署 Codex 容器

Codex 的部署我推荐用 docker compose，因为要配置的东西比较多，写成文件比一长串命令行参数清晰得多。

version: '3.8' services: codex: image: codex:latest container_name: codex ports: - "8080:8080" environment: - MODEL_ENDPOINT=http://host.docker.internal:11434 - MODEL_NAME=deepseek-coder:6.7b - TIMEOUT=120 - CONTEXT_WINDOW=8192 extra_hosts: - "host.docker.internal:host-gateway" restart: unless-stopped

extra_hosts那行是给 Linux 用户准备的，让容器能解析host.docker.internal。Windows 和 Mac 的 Docker Desktop 自带这个解析，但加上也不会有副作用。

启动：

docker compose up -d docker compose logs -f codex

看日志里有没有报错。常见的错误是连不上模型服务，这时候检查 Ollama 容器是不是在跑，端口是不是通的。

4.3 第三步：验证端到端链路

容器都起来之后，用 curl 测一下 Codex 的接口：

curl -X POST http://localhost:8080/v1/completions \ -H "Content-Type: application/json" \ -d '{ "prompt": "def fibonacci(n):", "max_tokens": 100 }'

如果返回了补全的代码，恭喜你，整条链路通了。如果报错，看 Codex 的日志，通常是模型地址配错或者模型名不对。

这一步跑通之后，你就可以把 Codex 接到编辑器插件里了。大多数编辑器插件支持配置自定义的 API 端点，把地址填成http://localhost:8080就行。

4.4 参数调优：让推理更快更稳

跑通只是第一步，用起来爽才是目的。本地推理有几个参数值得调：

num_ctx控制上下文长度，前面说过，按显存来设。num_gpu控制有多少层跑在 GPU 上，如果你的显存不够跑完整模型，可以设成部分层数，剩下的跑 CPU，速度会慢但至少能跑。temperature控制输出的随机性，写代码建议设 0.2 左右，太低会死板，太高会胡编。

Ollama 的这些参数可以在 Modelfile 里设，也可以在请求时传。我一般是在 Modelfile 里设好默认值，特殊场景再在请求里覆盖。

5. 常见问题与排查技巧实录

5.1 容器启动失败排查表

5.2 几个我踩过的坑

第一个坑是 Docker Desktop 的 WSL2 内存限制。Windows 上 Docker Desktop 默认只给 WSL2 分配一半物理内存，如果你有 32GB 内存，WSL2 只能用 16GB。跑大模型的时候会 OOM。解决办法是在用户目录下建一个.wslconfig文件，手动指定内存上限：

[wsl2] memory=24GB swap=8GB

改完wsl --shutdown重启 WSL 生效。

第二个坑是模型名大小写。Ollama 的模型名是大小写敏感的，DeepSeek-Coder和deepseek-coder是两个不同的东西。我因为这个排查了半小时，最后发现就是大小写问题。

第三个坑是防火墙。Windows 上第一次启动 Docker 容器映射端口时，防火墙会弹窗询问是否允许。如果你手快点了拒绝，后面怎么都连不上。去防火墙设置里手动放行对应端口就行。

第四个坑是磁盘空间。模型文件动辄几个 GB，Docker 镜像也不小，再加上容器日志，很容易把系统盘塞满。建议把 Docker 的数据目录迁到空间大的盘上，或者定期docker system prune清理。

5.3 性能不达预期的调优思路

如果你觉得推理速度慢，按这个顺序排查：

先看 GPU 利用率。nvidia-smi如果显示 GPU 利用率很低，说明模型大部分层跑在 CPU 上，需要调整num_gpu参数。再看显存占用，如果显存快满了，说明模型太大或者上下文设太长，需要降配。最后看是不是首次加载慢，模型第一次加载到显存需要时间，之后的请求会快很多。

CPU 推理的话，速度主要取决于内存带宽和核心数。DDR5 比 DDR4 快不少，核心数多的 CPU 也有优势。但说实话，CPU 推理跑 7B 模型，生成速度大概每秒几个 token，写代码补全勉强够用，复杂任务还是建议上 GPU。

6. 本地部署之后的使用心得

跑通本地 Codex 之后，我用了大概两个月，有几个真实体会想分享。

第一，本地部署的体验和云端差距在缩小，但还没到无感的程度。7B 量化模型在代码补全这种短任务上，响应速度和云端差不多，但遇到需要理解大段代码的重构任务，本地模型的能力明显弱一截。我的做法是分工：日常补全用本地，复杂重构还是切回云端。

第二，硬件投入要理性。我一开始想着一步到位上 32B 模型，结果发现 24GB 显存的卡价格不菲，而且功耗和散热都是问题。后来退回到 14B 量化，日常够用，电费也友好。建议先用手头的硬件跑起来，确认工作流真的用得上，再考虑升级。

第三，维护成本不能忽略。本地服务不是装完就一劳永逸，Docker 镜像要更新，模型要升级，偶尔还会遇到容器起不来的情况。如果你只是想偶尔用一下 AI 编程助手，云端方案其实更省心。本地部署适合的是那种每天都要用、对数据敏感、愿意花时间维护的开发者。

最后分享一个我常用的小技巧：把 Codex 和 Ollama 的启动命令写成一个 shell 脚本，开机自动拉起。这样你打开电脑就能用，不用每次手动敲命令。脚本里加个健康检查，服务没起来就自动重启，省心不少。