在日常的微服务开发中，命令行的自动补全（Tab Completion）绝对是提升效率的“神仙功能”。然而，当团队的自定义脚本或内部 API 逐渐增多时，给每个小工具写 Bash/Zsh 补全脚本就成了一件苦差事。前阵子，我突发奇想：能不能用 Node.js 快速写一个极简的、基于 HTTP 的 Tab Completion 服务，然后用 Docker Compose 一键暴露出来，让局域网里的开发伙伴都能通过简单的 curl 或是几行 Shell 钩子直接调用？

说干就干。这不仅是一次效率工具的探索，更是一场关于 Docker 网络、端口映射与 Shell 交互的“排错大戏”。

---

第一步：构建极简 Completion 服务

我们要实现的这个服务逻辑非常简单：接收一个当前输入的关键词 word，返回一组匹配的补全候选列表。这里我选择用高效的 Node.js (Express) 快速搭建。

首先是项目的目录结构：

mini-completion/
├── docker-compose.yml
├── Dockerfile
├── server.js
└── package.json

在 server.js 中，我硬编码了一些模拟的容器服务名称，作为补全的候选词：

const express = require('express');
const app = express();
const PORT = 8080;

// 模拟的补全候选词库（例如：团队内部的微服务名称）
const CANDIDATES = [
    'auth-service', 'payment-gateway', 'user-profile', 
    'analytics-dashboard', 'cache-redis', 'database-primary'
];

app.get('/complete', (req, res) => {
    const query = req.query.q || '';
    console.log(`[Received Query]: "${query}"`);
    
    // 过滤出以 query 开头的候选词
    const matches = CANDIDATES.filter(item => item.startsWith(query));
    
    // 以换行符分割返回，方便 Shell 脚本处理
    res.send(matches.join('\n'));
});

app.listen(PORT, '0.0.0.0', () => {
    console.log(`Completion service running on port ${PORT}`);
});

对应的 package.json 非常简单，只需依赖 express。而 Dockerfile 则采用了多阶段构建的轻量级方案：

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY server.js .
EXPOSE 8080
CMD ["node", "server.js"]

---

第二步：编写 Docker Compose 配置

为了让这个服务能够方便地暴露给本地宿主机，甚至局域网内的其他设备，我们需要通过 docker-compose.yml 来定义网络和端口映射。这里我将其暴露到宿主机的 9999 端口。

version: '3.8'

services:
  completion-svc:
    build: .
    container_name: mini_tab_completion
    ports:
      - "9999:8080"
    environment:
      - NODE_ENV=production
    restart: unless-stopped

一切准备就绪，执行启动命令：

docker compose up -d --build

终端输出了令人愉悦的绿字：

[-] Building 2.1s (9/9) FINISHED
[+] Running 2/2
 ✔ Network mini-completion_default  Created                                0.1s
 ✔ Container mini_tab_completion    Started                                0.3s

---

第三步：致命的 Bug 与深度排错

服务顺利启动了，我兴高采烈地准备在本地的 Zsh 中编写一个测试函数，用来实时拉取这个服务的补全结果。我写了如下的 Shell 钩子函数（简化版）：

# 模拟在终端输入时的补全调用
_mini_complete() {
    local word="${words[CURRENT]}"
    # 通过 curl 请求 Docker 暴露的服务，超时时间设为 1 秒
    local res=$(curl -s --max-time 1 "http://localhost:9999/complete?q=${word}")
    compadd $(echo "$res")
}
compdef _mini_complete mycli

然而，当我把这段代码光源注入到终端，并在输入 mycli au 然后按下 Tab 键的一瞬间，整个终端竟然直接卡死了！

没有出现预期的 auth-service，光标像僵尸一样固定在原地。过了足足好几秒，终端才恢复响应，并且什么补全提示都没有输出。

寻找蛛丝马迹

我立刻查看 Docker 容器的日志，发现了一件诡异的事情：

docker logs mini_tab_completion

输出竟然是空的！也就是说，server.js 根本没有打印出 [Received Query] 的日志。请求压根没有进到 Node.js 服务里。

难道是端口没映射成功？我尝试在宿主机直接用命令行测试：

curl -i "http://localhost:9999/complete?q=au"

这一次，终端疯狂报错：

curl: (7) Failed to connect to localhost port 9999 after 0 ms: Connection refused

深入剖析原因

“Connection refused”（拒绝连接）。我的 Docker Compose 明确写了 "9999:8080"，容器也明明显示正在运行。为什么会被拒绝？

我突然冷静下来，仔细审视了一下我当前的宿主机网络环境。由于我在公司内部使用了代理软件进行网络加速，并且本地配置了复杂的 HTTP_PROXY 和 HTTPS_PROXY 环境变量。

在 Shell 中执行 env | grep -i proxy 发现：

HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890

破案了！ 当我在终端按下 Tab 键触发 curl 时，Shell 脚本默认继承了当前环境变量中的 HTTP_PROXY。这就导致 curl "http://localhost:9999..." 的请求并没有直接发送给本地的 Docker 宿主机网络，而是被强行转发到了本机的 7890 代理端口。

而代理软件在处理 localhost 的流量时发生了回环阻断或解析错误，导致请求在代理层就被挂起、超时，最终引发了终端卡死，且 Docker 容器内部完全没有收到任何流量。

完美的 Fix 方案

要修复这个 Bug，有两步需要做。首先，最直接的办法是在 curl 请求中明确跳过代理，使用 --noproxy "*" 参数。

修改后的 Zsh 补全脚本如下：

_mini_complete() {
    # 获取当前光标处的输入
    local word=${words[CURRENT]}
    
    # 修复核心：加入 --noproxy "*" 强制走本地环回，并大幅缩短超时时间避免卡顿
    local res=$(curl -s --noproxy "*" --max-time 0.2 "http://127.0.0.1:9999/complete?q=${word}")
    
    # 将返回的换行数据转化为 Zsh 的补全数组
    if [ -n "$res" ]; then
        compadd ${(f)res}
    fi
}

重新加载 Shell 配置后，再次测试：

curl -s --noproxy "*" "http://127.0.0.1:9999/complete?q=pay"

瞬间返回：

payment-gateway

查看 Docker 日志，熟悉的字样终于跳了出来：

[Received Query]: "pay"

现在，在终端输入 mycli au 并按下 Tab，秒出 auth-service！那种丝滑的流畅感瞬间拉满。

---

学习感受与总结

这次折腾 Docker Compose 暴露微服务的经历，虽然看似只是做了一个小玩具，但带给我的技术体悟却非常深刻。

首先，Docker 的容器化确实极大地降低了环境部署的隐性成本。如果不用 Docker，我还得在本地配置 Node.js 环境、管理进程守护。而通过 Docker Compose，我不仅可以一行命令实现环境隔离，还能随时通过修改端口映射将其无缝分享给局域网的伙伴。

其次，开发中的“网络陷阱”无处不在。这次踩坑让我意识到，很多时候 Docker 容器本身没有问题，问题往往出在“宿主机通往容器”的桥梁上。本地代理环境变量（Proxy）经常充当“隐形杀手”，在搞网络或容器端口调试时，时刻保持对 localhost、127.0.0.1 以及代理路由的警惕，能少走很多弯路。

最后，把“高大上”的微服务架构和最底层的“Shell 命令行补全”结合在一起，让我切实感受到了自动化工具的魅力。用几行简单的代码解决每天都要面对的输入效率问题，这种成就感，大概就是程序员最纯粹的快乐吧。

本文包含AI生成内容