参考资料

• pnpm CLI
• pytest usage
• curl command line options
• Docker CLI
• Git documentation

生产工程（14） - 附录：常用命令

本文命令只使用相对路径和占位变量。 执行前先阅读项目 README、锁文件和脚本定义，不能假定每个仓库都使用相同端口或包管理器。 验收命令时同时看退出码、标准错误、生成物和状态变化，最后一行没有红字不代表成功。

一、确认运行时与工具链

node --version
corepack --version
pnpm --version
python3 --version
git --version
docker --version

• Node.js 版本应与 .node-version、.nvmrc 或 package.json#engines 一致。
• 包管理器与锁文件必须匹配，存在 pnpm-lock.yaml 时不要擅自改用 npm。
• Python 版本应与 pyproject.toml、.python-version 或部署镜像一致。
• CI 与本地工具链不同会让“本地通过”失去可复现意义。

二、Node.js 依赖安装

corepack enable
pnpm install --frozen-lockfile
pnpm list --depth 0

• --frozen-lockfile 禁止安装过程静默改写锁文件。
• 安装失败先看 Node.js 版本、锁文件格式、包源和原生依赖编译错误。
• 不用删除锁文件作为默认修复；这会改变整个依赖解析结果。
• pnpm list --depth 0 用于核对直接依赖，不证明运行时行为正确。

三、Node.js 静态检查与测试

pnpm lint
pnpm typecheck
pnpm test
pnpm build

• Lint 检查约定和部分缺陷，不能替代类型检查。
• 类型检查验证静态契约，不能证明运行时数据符合类型。
• 测试验证被覆盖行为，不能证明未覆盖路径正确。
• 构建验证生产产物能生成，仍需启动产物做冒烟测试。

四、定位可用脚本

pnpm run
node -p "require('./package.json').scripts"

• 先读取脚本定义，再决定执行 dev、start、test 或自定义命令。
• 不把文档中的通用脚本名当作仓库事实。
• 脚本调用其他工具时，错误退出码应向上传递。

五、创建 Python 虚拟环境

python3 -m venv .venv
source .venv/bin/activate
python -c "import sys; print(sys.executable)"
python -m pip --version

• sys.executable 应指向当前项目的 .venv。
• 使用 python -m pip 可以避免 pip 指向另一个解释器。
• 虚拟环境只隔离 Python 包，不隔离系统库、GPU 驱动或外部服务。

六、安装 Python 依赖

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip check

• 生产项目优先使用仓库已有锁定工具和锁文件。
• pip check 检查已安装包声明的依赖冲突，不验证 API 行为兼容。
• 安装失败要保留完整解析或编译日志，不要反复更换版本碰运气。

七、Python 质量检查

python -m ruff check .
python -m mypy .
python -m pytest -q

• 这些命令只有在项目声明对应依赖和配置时才执行。
• 单个失败测试可用完整节点 ID 重放，避免每次运行全库掩盖现场。
• 修复后仍要恢复执行相关测试集，防止只让单例通过。

八、运行单个 pytest 样本

python -m pytest tests/test_chat.py::test_rejects_oversized_context -vv
python -m pytest tests/test_chat.py -k "timeout or rate_limit" -vv

• -vv 帮助保留参数与断言位置。
• -k 是表达式过滤，不应作为永久跳过其他回归的方式。
• 随机失败要记录随机种子、并发、输入和外部依赖状态。

九、启动本地 API

python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

• 本地默认绑定回环地址，除非明确需要局域网访问。
• 模块路径和应用对象以当前项目为准。
• 启动日志出现端口不代表依赖就绪，仍需独立 readiness 检查。

十、检查监听端口

lsof -nP -iTCP:8000 -sTCP:LISTEN
curl --fail-with-body --max-time 5 http://127.0.0.1:8000/health

• 第一条确认哪个进程监听端口。
• 第二条要求 4xx 或 5xx 返回非零退出码，并限制总等待时间。
• 健康接口应区分存活和就绪，不能始终返回固定 200。

十一、验证 JSON API

curl --fail-with-body --max-time 30 \
  -X POST http://127.0.0.1:8000/api/chat \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <test-token>' \
  -H 'X-Request-Id: local-chat-001' \
  -d '{"message":"报销流程是什么？","session_id":"local-test"}'

• 使用测试令牌，不把真实 Key 写进 shell 历史或文章。
• 保存请求 ID 以关联应用日志、模型调用和检索 Trace。
• 同时验证非法 JSON、缺字段、无权限和超时路径。

十二、查看响应头和状态

curl --silent --show-error \
  --dump-header /tmp/chat-headers.txt \
  --output /tmp/chat-body.json \
  --write-out '%{http_code} %{time_starttransfer} %{time_total}\n' \
  http://127.0.0.1:8000/health

• 状态码、首字时间和总时间比肉眼观察页面更适合建立基线。
• 临时文件不得包含生产密钥和未脱敏业务数据。
• 命令成功后仍应解析必要 JSON 字段，而不是只检查 HTTP 200。

十三、验证流式响应

curl --no-buffer --fail-with-body --max-time 60 \
  -H 'Accept: text/event-stream' \
  http://127.0.0.1:8000/api/stream

• --no-buffer 让事件到达时立即显示，便于检查首块延迟。
• 验证事件类型、序号、完成事件和中途错误。
• 连接关闭不等于业务完成，必须看到协议约定的结束信号。

十四、Docker 构建

docker build --pull --tag ai-app:local .
docker image inspect ai-app:local

• --pull 尝试使用基础镜像的新版本，发布构建还应固定可审计的镜像摘要。
• 检查镜像入口、用户、环境变量和架构。
• 构建成功后要运行容器并验证健康与优雅停止。

十五、Docker 运行与日志

docker run --rm --name ai-app-local \
  --env-file .env.test \
  --publish 8000:8000 \
  ai-app:local

docker logs --timestamps ai-app-local

• .env.test 只能包含测试配置，并应被版本控制忽略。
• 不在命令行直接传真实 Key，避免出现在进程列表和历史记录。
• 日志应包含请求关联字段，不应包含完整 Prompt 或密钥。

十六、Docker Compose

docker compose config
docker compose up --build
docker compose ps
docker compose logs --timestamps --tail 200

• docker compose config 先解析合并后的配置，检查变量缺失。
• ps 需要同时看运行状态和健康状态。
• 停止测试环境使用项目明确的生命周期命令，避免误删共享卷。

十七、Git 变更范围

git status --short
git diff --stat
git diff --check
git diff

• status 确认修改与未跟踪文件范围。
• diff --stat 快速发现异常批量改写或大文件。
• diff --check 查尾随空格和冲突标记，不检查业务正确性。
• 完整 Diff 必须逐段阅读，不能只看统计。

十八、检查指定文件历史

git log --oneline -- path/to/file
git blame -L 20,60 -- path/to/file

• 历史用于理解约束和根因，不是修改无关旧代码的授权。
• blame 只显示最后一次逐行修改，不能独立证明设计意图。
• 发现用户未提交改动时要保留并与其协同，不能覆盖或还原。

十九、搜索代码与配置

rg -n "MODEL_NAME|BASE_URL|timeout" src tests
rg --files | rg '(^|/)(README|pyproject|package|Dockerfile)'

• 先用精确标识、错误码或字段名搜索，避免宽泛关键词制造噪声。
• 搜索结果要回到实际调用链和当前运行配置验证。
• 配置名相同不代表运行时一定读取了该文件。

二十、检查 JSON 与 YAML

jq . config/example.json
python -c "import yaml; print(yaml.safe_load(open('config/example.yaml')))"

• 解析成功只证明语法可读，不证明字段满足应用 Schema。
• 禁止用不安全 YAML loader 处理不可信输入。
• 配置验收还应启动应用或运行专用配置校验命令。

二十一、记录时间与退出码

time pnpm test
pnpm test
test_exit_code=$?
printf 'test_exit_code=%s\n' "$test_exit_code"

• 退出码必须在紧邻目标命令后读取。
• 不要在读取退出码前插入其他命令，否则记录的是错误对象。
• 性能比较要固定机器、负载、依赖和缓存状态。

二十二、命令失败时的判断顺序

1. 确认执行目录和目标仓库正确。
2. 确认命令来自当前项目脚本或官方文档。
3. 记录完整命令、退出码、标准输出和标准错误。
4. 核对运行时、依赖、环境变量和外部服务版本。
5. 用最小失败样本重放，每次只改变一个变量。
6. 修复后执行原失败命令和相关回归命令。

二十三、命令记录模板

字段	记录内容
目的	该命令验证哪个具体结论
目录	相对仓库根目录的位置
版本	代码、运行时、依赖和镜像
输入	参数、测试数据和脱敏配置
退出码	成功必须为预期退出码
输出	关键标准输出、错误和生成物
副作用	文件、数据库、队列或外部调用
回归	正常、边界和失败路径命令

二十四、总结

• 先识别项目约定：锁文件、脚本和版本声明优先于通用命令清单。
• 同时看证据：退出码、输出、产物和状态变化共同决定是否成功。
• 失败要可重放：保留目录、版本、输入和错误，不用重复运行碰运气。
• 发布要分层验证：Lint、类型、测试、构建、启动和健康检查不能互相替代。
• 保护敏感信息：测试 Key、脱敏数据和临时文件都要有明确边界。