企业官网建设流程全解析

1. 为什么要在华为云Flexus X实例上折腾CodeX Docs

CodeX Docs 是一个基于 Editor.js 生态的免费文档应用，它最大的特点是“无数据库依赖”——文档以本地文件或 MongoDB 存储，静态渲染出来的页面 URL 干净、对搜索引擎友好，同时支持文档嵌套、折叠侧边栏、错别字上报等实用功能。对于需要搭建产品手册、团队知识库、API 文档站点的中小团队来说，它比传统 Wiki 轻得多，也比纯静态生成器多了在线编辑能力。

我这次把它放在华为云 Flexus 云服务器 X 实例上跑，系统选的是 openEuler 22.03 LTS。Flexus X 实例的定位是柔性算力，vCPU 和内存配比可以自定义，对 CodeX Docs 这种“构建时吃 CPU、运行时吃内存不多”的应用来说很合适——构建阶段给它 4vCPU 能明显缩短依赖安装和 webpack 打包时间，跑起来之后 12GiB 内存又留足了余量给 Node.js 进程和后续可能接入的接口调用。

整个部署链路会覆盖几个关键环节：openEuler 下 Node.js 运行时的安装与全局链接、npm/yarn 镜像源切换、CodeX Docs 源码拉取与依赖安装、配置文件复制与鉴权参数修改、防火墙与安全组放行、最后通过首页访问、文档路由校验、接口连通性三步验证部署结果。同时我会把服务端 endpoint 改到 TaoToken 统一 Key 通道，这样后续如果 CodeX Docs 要调用模型能力做文档润色、摘要生成，鉴权配置只需要维护一处，不用在每个功能模块里重复填 Key。

如果你手头正好有一台 Flexus X 实例，或者准备在 828 期间入手一台做开发测试环境，这篇可以跟着一步步操作。下面先从环境准备讲起，再进入可复制的配置片段。

2. TaoToken 前置准备：统一 Key 通道与 endpoint 配置

CodeX Docs 本身是一个文档工具，但它预留了扩展接口，可以在文档编辑流程里接入外部服务做内容处理。为了让后续的模型调用、文档润色、摘要生成这类能力有一个统一的鉴权入口，我选择把服务端 endpoint 指向 TaoToken 的 API 通道。这样做的好处是：不管 CodeX Docs 内部有多少个需要调用模型的地方，Key 只在环境变量里维护一份，换 Key 或者调整模型时不用翻遍配置文件。

TaoToken 的 API 地址是https://taotoken.net/api，这个地址不带任何查询参数，直接作为 Base URL 使用。你需要先在 TaoToken 控制台创建一个 API Key，创建入口在控制台的 API Keys 页面。拿到 Key 之后，不要直接写死在代码里，而是通过环境变量注入，这样既方便切换环境，也避免 Key 被提交到 Git 仓库。

具体操作上，我建议在 CodeX Docs 项目根目录下创建一个.env文件，把 Base URL、Key、Model ID 三件套写进去。Model ID 根据你实际要用的模型填写，比如做文档润色可以选通用对话模型，做代码片段解释可以选代码能力强的模型。下面是一个可复制的.env示例：

# TaoToken 统一 Key 通道配置 TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_API_KEY=sk-你的实际Key TAOTOKEN_MODEL_ID=你的模型ID

写完之后用chmod 600 .env收紧权限，避免其他用户读取。然后在 CodeX Docs 的服务端启动脚本里通过process.env.TAOTOKEN_BASE_URL这种方式读取。如果你用的是npm start直接启动，可以在package.json的 scripts 里加一个dotenv预加载，或者用export $(cat .env | xargs)的方式在 shell 里注入。

这里有一个容易踩的坑：openEuler 默认的 shell 是 bash，.env文件里如果有空格或者特殊字符，用xargs注入时可能会截断。稳妥的做法是用set -a; source .env; set +a，这样每一行都会作为环境变量导出，Key 里的连字符和大小写都不会丢。

另外，如果你后续要用 Coding Plan 做长期编码或者 Agent 任务，可以在 TaoToken 控制台单独开一个 Coding Plan 的 Key，和文档工具的 Key 分开管理。这样即使文档工具的 Key 需要轮换，也不会影响编码任务的鉴权。模型对话功能则可以直接在模型对话页面测试 Key 是否可用，确认连通后再写进 CodeX Docs 的配置里。

3. 可复制配置：openEuler 下 Node.js 环境与 CodeX Docs 启动

这一节是整篇的核心操作区，我会把每一步的命令和配置文件都写全，你可以直接复制到终端执行。环境基线是 openEuler 22.03 LTS，内核 5.10，Node.js 选 v16.17.0，这个版本和 CodeX Docs 的依赖兼容性比较稳。

先确认系统版本和内核：

cat /etc/os-release uname -r

输出里应该能看到openEuler 22.03 LTS和5.10.0-60.109.0.136.oe2203.x86_64这样的内核版本。确认无误后，下载 Node.js 安装包。我用的是阿里云镜像，下载速度比官方源快很多：

cd /root wget https://mirrors.aliyun.com/nodejs-release/v16.17.0/node-v16.17.0-linux-x64.tar.xz tar -xvJf node-v16.17.0-linux-x64.tar.xz

解压完成后，把 node 和 npm 链接到/usr/local/bin，这样全局都能调用：

ln -s /root/node-v16.17.0-linux-x64/bin/node /usr/local/bin/node ln -s /root/node-v16.17.0-linux-x64/bin/npm /usr/local/bin/npm

接着配置环境变量。编辑/etc/profile，在末尾追加两行：

export NODE_HOME=/root/node-v16.17.0-linux-x64/bin/ export PATH=$PATH:$NODE_HOME:/usr/local/bin/

执行source /etc/profile让变量生效，然后验证：

node -v npm -v

正常应该输出v16.17.0和8.15.0。如果 node 命令找不到，检查一下软链接是否创建成功，或者echo $PATH看看/usr/local/bin是否在路径里。

接下来设置 npm 镜像源并安装 yarn。yarn 不是必须的，但 CodeX Docs 的 lock 文件是 yarn.lock，用 yarn 安装依赖更稳：

npm config set registry https://registry.npmmirror.com npm install -g yarn yarn config set registry https://registry.npmmirror.com yarn -v

yarn 版本应该是 1.22.x。然后拉取 CodeX Docs 源码：

cd /root git clone https://github.com/codex-team/codex.docs.git cd codex.docs

进入项目目录后，先看一眼结构，确认docs-config.yaml、package.json、src目录都在。然后安装依赖：

yarn install

这一步会花几分钟，取决于网络和 CPU。Flexus X 实例 4vCPU 的配置下，依赖安装大概两三分钟能完成。安装完成后，复制配置文件：

cp docs-config.yaml docs-config.local.yaml

编辑docs-config.local.yaml，重点改三个地方：port保持 3000，host改成0.0.0.0让外部能访问，auth.password改成你自己的密码。下面是一个改好的配置片段：

port: 3000 host: "0.0.0.0" uploads: driver: "local" local: path: "./uploads" frontend: title: "CodeX Docs" description: "Free Docs app powered by Editor.js ecosystem" startPage: "" auth: password: 你的访问密码 secret: 你的secret字符串 database: driver: local local: path: ./db

注意host如果保持localhost，外部浏览器是访问不到的，必须改成0.0.0.0。auth.secret用于会话签名，随便填一串足够长的随机字符即可。

启动服务可以用前台方式先测试：

npm start

看到Server started on port 3000之类的日志就说明起来了。确认没问题后，用后台方式跑：

npm start > output.log 2>&1 &

然后用jobs查看后台任务，或者tail -f output.log看实时日志。

最后处理防火墙和安全组。openEuler 默认可能开着 firewalld，先停掉并禁用：

systemctl stop firewalld && systemctl disable firewalld setenforce 0 sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config

然后在华为云 Flexus X 实例控制台的安全组入方向规则里放行 3000 端口。这两步缺一不可，防火墙关了但安全组没放行，外部照样访问不了。

4. 验证请求：首页访问、文档路由与接口连通性三步校验

部署完成后不能只看进程在不在，得实际发请求验证。我一般分三步：先访问首页确认服务活着，再校验文档路由确认静态渲染正常，最后测接口连通性确认 TaoToken 通道可用。

第一步，首页访问。在浏览器里打开http://你的弹性公网IP:3000，如果能看到 CodeX Docs 的初始页面，说明 Node.js 服务、端口监听、安全组放行这三件事都对了。如果打不开，先在服务器上用curl -I http://127.0.0.1:3000看本地是否返回 200，本地通但外部不通，基本就是安全组或防火墙的问题。

第二步，文档路由校验。在 CodeX Docs 里新建一个页面，填写访问密码（就是docs-config.local.yaml里auth.password的值），编辑内容后保存。然后访问这个文档的 URL，比如http://你的IP:3000/你的文档路径，确认页面能正常渲染出你编辑的内容。这一步验证的是静态渲染和本地数据库读写是否正常。如果保存后刷新页面内容丢失，检查database.local.path指向的./db目录是否有写权限。

第三步，接口连通性。这一步验证 TaoToken 通道是否配通。在服务器上用 curl 发一个请求到 TaoToken 的 API 地址，带上你的 Key：

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$TAOTOKEN_MODEL_ID"'", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10 }'

如果返回里能看到choices字段和模型输出，说明 Key、Base URL、Model ID 三件套都正确。如果返回 401，检查 Key 是否复制完整、有没有多余空格；如果返回local proxy failed之类的错误，检查服务器出网是否正常，curl -I https://taotoken.net看能不能通。

三步都通过后，你可以在 CodeX Docs 的服务端代码里把需要调用模型的地方指向TAOTOKEN_BASE_URL，这样文档润色、摘要生成这类功能就有了统一的鉴权入口。模型对话页面也可以用来快速测试不同模型在文档场景下的表现，确认哪个 Model ID 更适合你的文档风格。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

部署和接入过程中，报错基本集中在几个地方。我把实际遇到过的和社区里高频出现的整理出来，对照着排查能省不少时间。

401 Unauthorized：这个最常见，出现在调用 TaoToken API 的时候。原因通常是 Key 不对、Key 过期、或者请求头格式写错。检查Authorization头是不是Bearer sk-xxx的格式，Bearer 和 Key 之间有一个空格。另外确认.env文件里的 Key 没有被 shell 截断，用echo $TAOTOKEN_API_KEY打印出来对比一下长度。如果 Key 是在控制台刚创建的，确认没有复制到多余的空格或换行。

local proxy failed：这个报错通常出现在服务器无法出网，或者 DNS 解析失败的时候。先在服务器上执行curl -I https://taotoken.net，如果卡住或者报连接失败，检查 Flexus X 实例的弹性公网 IP 是否绑定、安全组出方向是否放行 443 端口。openEuler 默认的出方向规则一般是全放行的，但如果你改过安全组，需要确认一下。另外检查/etc/resolv.conf里的 DNS 配置，换成114.114.114.114或8.8.8.8试试。

reading choices 报错：这个一般是在解析 API 返回时出现的，说明返回体里没有choices字段。可能的原因是 Model ID 填错了，或者请求体格式不对。先用 curl 单独测一次，确认返回体结构。如果返回的是{"error": {...}}，根据 error message 调整。Model ID 要和 TaoToken 控制台里显示的完全一致，大小写敏感。

OAuth 相关报错：如果你在 CodeX Docs 里配置了第三方登录或者 OAuth 回调，报错通常和回调地址、client secret 有关。CodeX Docs 本身默认用密码鉴权，OAuth 是可选扩展。如果不需要 OAuth，直接在配置里不启用即可。如果确实要用，确认回调 URL 里的域名和端口与实际访问地址一致，http://IP:3000和http://localhost:3000在 OAuth 流程里会被视为不同来源。

CC Switch / Cline MCP / Codex auth.json 三件套：如果你后续要把 CodeX Docs 和编码工具链打通，比如用 CC Switch 管理多个模型的切换，或者用 Cline 的 MCP 做文档检索，那么 Base URL、Key、Model ID 这三件套必须写全。CC Switch 的配置文件里通常有baseUrl、apiKey、model三个字段，分别对应https://taotoken.net/api、你的 Key、你的 Model ID。Codex 的auth.json里则是api_base、api_key、model这样的键名。不管哪个工具，缺一个都会导致鉴权失败或者模型调用报错。

排查的时候有一个通用思路：先用 curl 在服务器本地测通 API，再在应用层测。本地 curl 通了，说明网络和 Key 没问题，问题就在应用配置；本地 curl 不通，先解决网络和 Key 的问题，别急着改应用代码。

6. 把 endpoint 固定到 TaoToken 通道后的长期维护建议

部署完成只是开始，后面要长期用起来，有几个维护习惯值得养成。第一，把.env文件加入.gitignore，Key 永远不进版本库。如果团队多人协作，每个人用自己的 Key，通过环境变量注入，而不是共享一个 Key。第二，定期在 TaoToken 控制台检查 Key 的使用量和余额，避免因为额度耗尽导致文档工具的扩展功能突然不可用。第三，如果 CodeX Docs 后续升级版本，先备份docs-config.local.yaml和db目录，再拉新代码，避免配置被覆盖。

对于需要长期编码或者跑 Agent 任务的场景，可以单独开一个 Coding Plan 的 Key，和文档工具的 Key 分开。这样文档工具的 Key 权限可以收窄，只允许调用模型对话接口，降低泄露风险。模型对话页面可以作为一个轻量的测试入口，每次换 Model ID 之前先在那里验证一下返回是否正常，再写进 CodeX Docs 的配置。

如果你还没开始部署，可以先在 TaoToken 控制台创建 Key，然后从 Node.js 环境安装那一步跟着做。整个流程在 Flexus X 实例 4vCPU 12GiB 的配置下，从零到访问首页大概十五到二十分钟。踩过的坑基本都在第五节里了，遇到报错先对照排查，大部分问题出在 Key 格式、host 绑定和安全组这三处。