linux-command私有化部署：搭建内网Linux命令速查手册

团队里的服务器一多，最常被翻出来的不是监控面板，而是各种“Linux 常用命令”的收藏夹。收藏夹里攒了上百个链接，真到排查问题的时候却又卡在“记不清参数、网又打不开、规则对不上”这三个坎上。尤其在内网隔离环境下，命令手册这种东西越依赖外网，越耽误事。

linux-command 这个开源项目解决的就是这个问题：把日常开发、运维里真正用得上的 Linux 常用命令沉淀成一套可检索、可浏览、可自定义的 Web 手册，然后允许你把它完整地部署到自己的服务器上。我在给团队内部落地这套“命令库”的过程中，踩过不少坑，也整理出一条从拉代码到上线、再到日常维护的完整链路。这篇文章主要写给两类人：一类是负责搭建内网工具平台的运维或开发，另一类是希望有一份不依赖外部网络的本地命令参考，随时能在浏览器里查参数、抄示例的伙伴。全程用真实操作串起来，你可以照着一步步执行，也可以直接跳到自己关心的那节。

1. linux-command 到底是个什么东西，值不值得部署

1.1 它不只是“一堆命令的列表”

很多人第一次看到 linux-command 仓库，会误以为它就是一个 Markdown 文档堆。实际用下来你会发现，它更像一个“命令查询搜索引擎”。仓库里有一个 commands/ 目录，里面按命令名保存了大量 Markdown 文件，例如 ls.md、grep.md、systemctl.md，每个文件都会把“命令用途、语法格式、参数说明、常用示例”这四件事讲清楚。

关键部件是这个 Web 站点：构建之后会生成一个静态页面，带命令搜索、目录分类、示例代码高亮，甚至还能直接复制命令文本。搜索逻辑跑在浏览器端，不需要后端接口，也不需要数据库，打开页面即用。这些特性叠加起来，让它非常像一个“离线可用的 Linux 速查站”。

这里的“离线”有两个含义。一是物理离线：把构建产物放内网，没有外网也能正常用；二是依赖离线：整个查询过程不依赖任何第三方在线服务，哪怕把过程日志关掉，单人单机也能跑得飞快。

1.2 相比普通网页收藏夹，它的三个优势

首先是搜索效率。普通手册站要在输入框里敲回车，然后等服务器响应；linux-command 的页面打开后，输关键字是实时过滤的，基本不用等。对运维来说，“记不住参数名”到“看到参数含义”的时间越短，排查问题的心理压力越小。

其次是内容可控。部署之后，commands/ 目录完全归你管。团队内部有一些自己的命令规范、禁用的参数、特有的启动脚本，都可以直接追加进去，重新构建一次就出现在站点里。这一点是外部在线文档做不到的，也是“私有化”的最大红利。

最后是轻量。整个项目的静态产物不过几十 MB 量级，一块最低配的内网虚拟机就能带起来，不需要为它单独买资源。它不会像那些重型的知识库系统一样要求你维护数据库、搜索服务器、容器编排，上手难度几乎为零。

1.3 项目定位决定了部署方案不会复杂

很多团队一听到“私有化部署”四个字，下意识就以为要搞一套 Kubernetes、对象存储、网关集群出来。但对 linux-command 来说，真没有必要。它的本质是一个静态站点生成项目，你只需要解决两件事：把代码变成静态文件，再用一个 Web 服务把静态文件发布出去。一个 Nginx 加一段 Node 构建脚本，或者一个 Docker 容器，就能覆盖 90% 的场景。

所以在动手之前，你先在心里画个框：这项目是“工具型”的，不是“平台型”的。不要被名字里的“私有化部署”吓到，它要求的其实只是“一个能长期运行的进程”而已。抱着这个判断，后面所有选择都会简单很多。

2. 部署方案怎么选：静态发布还是容器化运行

2.1 先问自己三个问题

开始部署之前，先把环境想清楚，能省不少返工的时间。

第一问：访问入口是什么？如果只是你和同事在办公室浏览器里用，一台内网服务器加一个端口就够了；如果需要挂在团队统一的技术门户下，那就要考虑路径前缀，而不是独立域名。

第二问：更新频率有多高？命令手册这种东西，通常不会天天改，但每年至少会有几次命令版本迭代。如果你希望以后按一下脚本就能重建，静态构建方案更顺手；如果你希望“拉取新镜像、重启容器”就完成更新，容器方案更合适。

第三问：目标机器有没有外网权限？如果服务器完全离线，你需要事先在能联网的机器上把代码仓库和依赖全部拉下来，打成离线包拷进去。这一步决定了你是走在线构建，还是提前准备完整资源。

这三个问题中没有绝对正确答案，但它们会直接影响你选的部署路径。我的建议是：单机、内网、只给少量团队用的，选择静态发布 + Nginx；如果团队比较喜欢用 Docker 管理组件，统一走容器方式。两者本质是一回事，只是封装层不同。

2.2 两种落地方式的对比

我本地维护了两套环境，一套用静态发布，一套用 Docker，原因是两种方式各有适用场景。静态发布适合我折腾命令内容，改完直接替换目录；Docker 适合快速迁移，在一台新机器上几十秒就能起一个新实例。

下表是两种方式的直观对照：

对比项	静态站点方案	容器化方案
依赖件数	只需要 Git、Node、Nginx	只需要 Docker
构建过程	手动/脚本执行 npm build	打镜像时统一完成
更新方式	重新构建后替换静态目录	重新 build 镜像并替换容器
迁移难度	拷贝 dist 目录即可	导出/导入镜像或重拉即可
适合场景	单机、内网、个人折腾	团队标准化、快速恢复
排障难度	相对直接	需要看容器日志和挂载

这两条路我都走通了，后文的实操流程会分成两段，你先选一条主线，另一条可以作为备用方案存在。

2.3 硬件要求低到什么程度

我曾经把 linux-command 跑在一台只分到 1 核 CPU、512MB 内存的闲置虚拟机上，页面响应依旧很快。因为它所有压力都在浏览器端，服务端只负责吐静态文件，CPU 和内存的占用几乎可以忽略。

磁盘方面，代码仓库加依赖加构建产物，全部算下来通常不会超过 800MB，其中大头是 node_modules。如果你用容器方式，镜像本身也不大，日常维护基本不需要考虑磁盘扩容。真正需要小心的反而是构建阶段的临时空间，如果服务器根目录比较紧张，建议先执行 df -h 确认一下，免得构建到一半磁盘写满。

3. 实操准备：环境依赖、目录规划与基础配置

3.1 登录服务器后先做的三件事

不管用哪种方案，我都建议先把基础环境过一遍。以 CentOS 或 Rocky Linux 为例，登录之后按顺序执行下面的检查。

先看系统版本，方便后面装对应包：

再看磁盘余量和内存：

最后确认有没有装过 Git 和 Node：

没有安装 Git 的话，用系统自带包管理器安装。Ubuntu/Debian 系用 apt，CentOS/Rocky 系用 dnf 或 yum，不要混用，否则容易踩依赖坑。

3.2 安装 Node.js 和构建工具

linux-command 的构建需要 Node.js 环境。我建议直接安装 Node 的 LTS 版本，太老的版本跑依赖安装时经常报错，太新的版本偶尔会和项目的旧依赖有兼容性摩擦。

在 Ubuntu 上，比较稳妥的做法是先启用 NodeSource 仓库再安装：

在 CentOS/Rocky 上，同样可以用 NodeSource 仓库：

安装之后确认版本：

这里有个小经验：不要在这台机器上为了其他项目随意切换 Node 版本。这个命令库项目不复杂，但 Node 版本换来换去，node_modules 里某些二进制模块可能会识别不到新版本导致构建失败。固定一个 LTS 版本最省心。

3.3 规划目录、端口和用户

我习惯把这类内部工具统一放在 /opt/ 下，不放在 /root 或 /home。一方面避免权限混乱，另一方面方便写脚本管理。具体目录如下：

• 代码目录：/opt/linux-command
• 构建产物：/opt/linux-command/dist
• 备份目录：/opt/linux-command-backup
• 日志目录：/var/log/linux-command/

端口上，我建议不要直接用 80。因为 80 端口通常还要留给团队其他服务，比如内部 Wiki 或监控面板。linux-command 我分配在 8080，再用统一入口按域名转发过去。这样以后做迁移，改动面最小。

如果你不想以 root 身份跑服务，可以新建一个专用用户：

给部署目录授权：

后续构建都用这个用户执行，避免服务以高权限运行。这个习惯在团队规范化管理中很重要，虽然只是一个小工具页面，但权限收敛的策略应该一致。

4. 从 0 到 1 完成部署的完整流程

4.1 拉取代码并确认目录结构

登录服务器，切到目标目录，然后把项目克隆下来。这里以 GitHub 仓库为例：

注意命令结尾的点，表示克隆到当前目录。如果目录里已经有其他文件，先清空或者换一个干净的目录。

克隆完成后，先看目录：

正常你会看到类似下面的内容：

目录/文件	作用
commands/	所有命令的 Markdown 源文档
src/ 或 web/	构建脚本和前端源码
package.json	依赖与构建命令定义
.github/	自动化流程配置

不要急着动手构建，先看 package.json 里的 scripts 段落，确认这个版本的构建命令名。绝大多数情况下是 npm run build，但小版本差异可能导致命令名变化，看一眼最稳：

4.2 安装依赖并构建静态站点

确认无误后开始装依赖。这一步耗时取决于网络环境，可能要几分钟：

如果安装过程中报权限错误，检查是否用了普通用户，避免用 root 直接安装。如果因为历史遗留问题导致 node_modules 不干净，先删掉再装：

依赖装好后，直接执行构建命令：

构建完成后，dist 目录就会出现。这个目录就是整个站点的完整产物，里面是后缀为 html、js、css 的文件，不需要任何后端进程配合。你可以先在这个目录里确认下文件数量：

看到非空文件列表，就说明构建成功了。

4.3 用 Nginx 提供服务

Linux 命令工具就该有符合 Linux 气质的发布方式，Nginx 是最常见的选择。先安装：

然后写一个站点配置。这里我故意避开一条典型的踩坑路：不要直接改 nginx.conf 主干，而是在 conf.d 或者 sites-available 下单独建文件，保持配置隔离。

在 /etc/nginx/conf.d/linux-command.conf 下写入：

这中间有一行 try_files 很关键。因为站点内部有前端路由，如果用户直接访问某个子路径，而 Nginx 在该路径下找不到真实文件，就会返回 404。加了这一行，Nginx 会把所有没匹配上的请求都交给 index.html，由页面自己去渲染对应视图。这是静态站点上线最容易忽略的环节，没有它，首页看着正常，点进某个命令详情页再刷新就直接白屏或者报错。

配置写完，先做语法检查：

输出 syntax is ok 之后再重载配置：

到这一步，浏览器访问 http://服务器IP:8080 就应该能看到熟悉的命令搜索页了。

4.4 容器化部署路线

如果你更习惯用 Docker 管理组件，流程会再缩短一截。进入项目目录，直接用仓库里的 Dockerfile 构建镜像：

构建完成后运行容器：

这里有两处细节。第一，--restart=always 保证服务器重启后容器会自动拉起，少了这个参数，只要宿主机重启一次，服务就静悄悄没了。第二，映射端口 8080:80，意思是宿主机 8080 转发到容器内部 80，而 Nginx 是在容器内部运行的，所以访问方式和静态方案完全一致。

容器跑起来以后，查看状态：

再验证页面能不能访问：

能看到 HTTP/1.1 200 OK，说明整套链路通了。容器方案的另一个好处是回滚简单：老镜像不用删，启动新容器之前把旧容器停掉，一分钟内就能完成版本切换。

5. 验证、自定义与日常维护

5.1 上线验证清单

部署成功不等于上线完成，我习惯按下面这张清单走一遍验证流程：

检查项	操作	预期结果
首页渲染	浏览器打开页面	搜索框和命令分类正常显示
搜索功能	输入 tar	实时返回 tar 命令及参数说明
命令详情	点击任意命令	页面能跳转且刷新后不报错
复制功能	点击示例旁的复制按钮	剪贴板能拿到正确内容
移动端显示	手机浏览器访问	布局不横向溢出
并发访问	同时让 10 个同事打开页面	无明显卡顿

如果验证过程中发现样式丢失或者接口报错，按照后面常见问题一节去排查，大部分问题都在构建或路径配置上。

5.2 把团队私有命令加进去

linux-command 的扩展性很好。假设你们团队内部有一个启动服务的标准脚本，比如 svc-start，你想让它也出现在站点的命令列表里，做法很简单。

在 commands/ 目录下新建一个 svc-start.md，内容按照项目约定写清楚：

保存文件后，重新执行构建：

再把 dist 目录替换成新产物即可。如果是 Nginx 静态方案，直接整体覆盖：

如果是 Docker 方案，需要重新构建镜像。整个流程结束后，你就能在站点的命令索引里搜到 svc-start 了。

5.3 写一个自动化更新脚本

命令手册的价值在于及时跟上游同步。我不会手工去拉代码，而是写一个更新脚本，固定周期执行。

脚本内容大致如下：

这个脚本里，备份是最容易被省略但又最值得做的一步。命令手册虽然内容敏感度不高，但它会被团队当成参考资料，万一更新后命令格式出现兼容问题，有备份就能快速回滚到旧版。配合 crontab 每周执行一次：

添加一行：

注意把执行权限加上：

这样每周一凌晨两点会自动跑一次更新。如果团队里有人专门维护这套工具，也可以改成手动触发。

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

6.1 构建阶段的三类经典报错

构建阶段是坑最多的地方。我遇到过三类高频问题，这里直接给原因和解决方法。

第一类：npm install 卡死或者报各种网络超时。这种情况通常发生在公网访问受限时，依赖下载量太大导致连接被断开。解决办法是先确认网络，再考虑离线安装依赖包。可以把整个项目目录在能联网的机器上构建一次，将 node_modules 目录连同 dist 一起打 tar 包，拷进内网直接释放。

第二类：node-sass 相关报错，类似 Error: Missing binding。这是因为 Node 版本和 node-sass 的二进制版本对不上。老依赖在 Node 16 以上经常会出问题。我的处理方式是先删掉 node_modules 和 package-lock.json，再用当前 LTS 版本重新安装；如果还不行，就检查项目是否已经把依赖迁移到了 sass，对应调整构建命令。

第三类：磁盘空间不足。构建过程中的临时文件和 node_modules 会同时存在，占用比最终产物高出不少。遇到 ENOSPC 报错，先清理 npm 缓存：

然后检查根分区剩余空间，如果确实紧张，把项目挪到空间更充裕的挂载点，或者在构建前删除旧备份。

6.2 页面能打开但样式全丢

这是非常典型的问题，通常不是你代码的问题，而是 Nginx 没有正确返回静态资源。页面能打开说明 HTML 出来了，但 CSS、JS 等静态文件路径不对，导致页面没有样式、没有任何可点击内容。

排查时先看浏览器控制台的资源加载报错，再对比 Nginx 配置文件里的 root 字段。如果你把项目构建产物放到了 /opt/linux-command/dist，但 root 写成了 /opt/linux-command，Nginx 就会到 /opt/linux-command/css/ 去找文件，而实际文件在 /opt/linux-command/dist/css/，自然全部 404。

这个问题的特征就是“HTML 有，资源没有”，遇到它不要怀疑构建流程，先检查 nginx -T 里实际生效的 root 路径。

6.3 端口开了却访问不了

很多时候服务本身已经起来了，但就是访问不到。如果 curl http://127.0.0.1:8080 正常，而局域网其他机器打不开，大概率是系统防火墙或者云安全策略没有放行端口。

CentOS/Rocky 上，检查 firewalld 状态并放行端口：

Ubuntu 上，用 ufw：

如果服务器启用了 SELinux，Nginx 访问非常规目录可能也会被拦截。查看审计日志：

确认是 SELinux 干扰后，更稳妥的做法是把构建产物放到允许 Web 服务访问的目录下，或者按实际需要调整策略。不要图省事直接关掉 SELinux，保持系统原有安全策略是团队纪律。

6.4 Docker 容器重启后不见了

用 Docker 部署之后，最常见的一个问题发生在宿主机重启之后：页面访问不了了，一查容器状态，发现容器处于 Exited 状态或者根本没有启动。这多半因为启动容器时漏了 --restart=always。

如果已经漏了，补救命令如下：

如果你用的是 docker-compose 管理，那么在 docker-compose.yml 里加：

在使用容器方案时，我还会检查容器内部的数据是否挂载到宿主机。linux-command 主要存的是静态文件，但如果后续要做命令自定义，重新构建镜像时容易丢改动，把代码目录挂载出来会稳妥得多。

6.5 常用问题速查表

现象	常见原因	优先处理方式
npm install 卡住	网络受限或缓存过期	离线打包依赖 / 清缓存重装
构建报 node-sass 错误	Node 版本与依赖不匹配	重装依赖、固定 LTS 版本
页面有 HTML 没样式	Nginx root 路径不对	检查 root 与 dist 层级
详情页刷新 404	缺少 try_files 规则	增加 try_files $uri $uri/ /index.html;
局域网无法访问	防火墙/云安全组未放行	放行对应端口
容器重启后消失	缺少 --restart=always	docker update --restart=always 容器名
页面字迹模糊	低端机型访问高分辨率图	检查浏览器缩放和资源加载

这张表我打印出来贴在工位上，每次给新同事讲这套工具时就指着说：先按表排除，解决不了再往深处查。

7. 部署完还能延伸的玩法，以及我的个人体会

7.1 把命令库接入团队统一入口

很多团队有内部的工具导航页，linux-command 完全可以以子栏目的形式挂进去。如果入口是用 Nginx 统一转发，只需要把站点配置放到对应路径下即可。这样一来，团队只有一个统一访问入口，不需要每个人都记住这台工具的 IP 和端口。部署工具的价值不在于工具本身，而在于它能不能被团队随手用起来。

7.2 用一份命令规范约束日常工作

私有化部署还有一个隐藏红利：可以把团队里约定俗成的命令规范沉淀进去。比如说，生产环境禁用某个危险参数、所有日志查看看哪些统一用 journalctl、服务启停统一走 service 脚本，这些内容都可以写成公司内部命令条目。新人入职不再需要翻聊天记录找老同事要命令，打开内网手册一搜就有，而且搜索结果和团队规范严格一致。用久了你会发现，工具最终沉淀的是团队的做事方式。

7.3 后续还可以扩展什么

有精力的话，可以从两个方向继续扩展。一是给命令文档增加按业务场景的分类，比如“安全排查”“性能分析”“日志检索”，让运维在处理具体问题时能快速缩小范围。二是把站点里新增的命令数据导出成 JSON，喂给团队内部的 AI 助手，做成“问一句话就返回对应命令示例”的功能。底层数据还是这份命令库，接口和交互可以再包装。

7.4 踩坑之后的几句真话

这套部署跑了大半年，我的体会是：不要把 linux-command 当成一个“部署完就不管”的静态页面。它的价值是在长期维护中体现的。每次系统升级、命令行为变化、团队规范调整，都应该回来更新这份手册。否则用不了多久，站点就会变成一份“过时的旧命令大全”，失去参考价值。

最后分享一个小技巧：在 commands/ 目录里新增命令时，文件名尽量和命令名保持一致，内容里不要塞太多废话。这个站点搜的是命令名和关键词，写得越规范，命中率越高。保持目录整洁，比任何花哨的界面优化都重要。毕竟，工具型产品的本质，是让你在最需要帮助的几秒钟里，找到那一条正确的命令。