vps-dependency-overview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dependency Overview (Docker-compose monorepo)

依赖概览（Docker-compose单体仓库）

Inventory script that walks a

services/

directory of Docker-compose stacks and produces a Markdown or JSON report of:

Compose images —
```
image:
```
references with tag/digest, classified by pinning quality (
```
floating
```
,
```
implicit-latest
```
,
```
major
```
,
```
minor
```
,
```
semver
```
,
```
digest
```
,
```
custom
```
)
Build services —
```
FROM
```
lines from Dockerfiles, useful for spotting outdated base images
Runtime hints — Node/Python versions inferred from
```
.nvmrc
```
,
```
.node-version
```
,
```
.python-version
```
,
```
package.json
```
engines,
```
pyproject.toml
```
Dependency manager signals — which lockfiles exist (
```
pnpm-lock.yaml
```
,
```
package-lock.json
```
,
```
poetry.lock
```
,
```
uv.lock
```
, …)
Per-service update-check skills —
```
<service>/.agents/skills/*-update-check/
```
if you've put deeper version-checking skills next to each service

It does not hit the network. It answers "what am I using?", not "what's the latest?".

这是一个清单脚本，会遍历Docker-compose栈的

services/

目录，生成Markdown或JSON格式的报告，内容包括：

Compose镜像 —
```
image:
```
引用的标签/摘要，按版本固定质量分类（
```
floating
```
、
```
implicit-latest
```
、
```
major
```
、
```
minor
```
、
```
semver
```
、
```
digest
```
、
```
custom
```
）
构建服务 — Dockerfile中的
```
FROM
```
行，有助于发现过时的基础镜像
运行时提示 — 从
```
.nvmrc
```
、
```
.node-version
```
、
```
.python-version
```
、
```
package.json
```
engines、
```
pyproject.toml
```
推断出的Node/Python版本
依赖管理器信号 — 存在哪些锁文件（
```
pnpm-lock.yaml
```
、
```
package-lock.json
```
、
```
poetry.lock
```
、
```
uv.lock
```
等）
单服务更新检查技能 — 如果你在每个服务旁放置了更深入的版本检查技能，会显示
```
<service>/.agents/skills/*-update-check/
```

该脚本不会访问网络。它回答的是“我正在使用什么？”，而非“最新版本是什么？”。

Quick Start

快速开始

From the repo root, with

docker compose

(v2) available locally:

bash

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py \
  --format markdown \
  --output /tmp/dependency-overview.md

Print to stdout instead:

bash

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --format markdown

Focus on specific service folders:

bash

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --only n8n --only postgres

JSON output for downstream tooling:

bash

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --format json

在仓库根目录下，确保本地已安装

docker compose

（v2）：

bash

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py \
  --format markdown \
  --output /tmp/dependency-overview.md

直接输出到标准输出：

bash

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --format markdown

聚焦特定服务文件夹：

bash

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --only n8n --only postgres

生成JSON格式输出供下游工具使用：

bash

python3 .agents/skills/vps-dependency-overview/scripts/vps_dependency_overview.py --format json

Flags

命令行参数

Flag	Default	Description
`--root`	`.`	Workspace root
`--services-dir`	`services`	Subdirectory containing per-service folders
`--format`	`markdown`	`markdown` or `json`
`--output`	stdout	Write to a file instead of stdout
`--only NAME`	all	Restrict to specific service folder names (repeatable)

参数	默认值	描述
`--root`	`.`	工作区根目录
`--services-dir`	`services`	包含各服务文件夹的子目录
`--format`	`markdown`	输出格式： `markdown` 或 `json`
`--output`	标准输出	将结果写入文件而非标准输出
`--only NAME`	所有服务	限制为特定服务文件夹名称（可重复使用）

Expected layout

预期目录结构

<root>/
  <services-dir>/             # default: services/
    <service-a>/
      docker-compose.yml      # required for the service to be inventoried
      Dockerfile              # optional, parsed if present
      .nvmrc / .python-version / package.json / pyproject.toml   # optional, parsed for runtime hints
      .agents/skills/<svc>-update-check/SKILL.md                 # optional, surfaced in the report
    <service-b>/
      ...

A service folder without

docker-compose.yml

is skipped silently.

<root>/
  <services-dir>/             # 默认：services/
    <service-a>/
      docker-compose.yml      # 服务被纳入清单的必填文件
      Dockerfile              # 可选，若存在则会被解析
      .nvmrc / .python-version / package.json / pyproject.toml   # 可选，用于推断运行时提示
      .agents/skills/<svc>-update-check/SKILL.md                 # 可选，会在报告中显示
    <service-b>/
      ...

不含

docker-compose.yml

的服务文件夹会被自动跳过。

Requirements

环境要求

Python 3.11+ (uses
```
tomllib
```
)
```
docker
```
with Compose v2 (the script invokes
```
docker compose -f … config --format json
```
to resolve compose files; no images are pulled or built)

Python 3.11+（使用
```
tomllib
```
库）
带有Compose v2的
```
docker
```
（脚本会调用
```
docker compose -f … config --format json
```
来解析compose文件；不会拉取或构建镜像）

Optional: live container versions on a remote host

可选功能：远程主机上的实时容器版本

The script reports desired versions (what the compose files say). To compare against actually running versions on a remote VPS, run separately:

bash

ssh <vps-host> "docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'"

Replace

<vps-host>

with your SSH alias from

~/.ssh/config

脚本报告的是预期版本（compose文件中声明的版本）。如需与远程VPS上实际运行的版本对比，请单独执行以下命令：

bash

ssh <vps-host> "docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'"

将

<vps-host>

替换为

~/.ssh/config

中的SSH别名。

How to read the report

报告解读

Pinning class	What it means	Reproducibility
`digest`	`image@sha256:…`	Best — content-addressed
`semver`	`1.2.3` , `v1.2.3` , `1.2.3-alpine`	Good — explicit version
`minor`	`1.2` , `1.2-alpine`	Major+minor pinned, patches float
`major`	`22` , `3-slim`	Major pinned, minor+patch float on rebuild
`floating`	`latest` , `main` , `master` , `edge` , `stable`	Bad — non-reproducible
`implicit-latest`	no tag at all	Bad — equivalent to `:latest`
`custom`	anything else	Worth a manual look

Runtime fields:

```
node_container
```
/
```
python_container
```
— inferred from Dockerfile
```
FROM
```
lines (the runtime your container actually runs)
```
node_repo
```
/
```
python_repo
```
— inferred from
```
.nvmrc
```
/
```
.python-version
```
(what dev tooling expects)

node_engine

python_requires

— explicit constraints from

package.json

pyproject.toml

A common red flag:

node_container=18

while

node_repo=22

means your dev environment and your container are on different majors.

版本固定分类	含义	可复现性
`digest`	`image@sha256:…`	最佳——基于内容寻址
`semver`	`1.2.3` , `v1.2.3` , `1.2.3-alpine`	良好——明确版本
`minor`	`1.2` , `1.2-alpine`	固定主版本+次版本，补丁版本浮动
`major`	`22` , `3-slim`	固定主版本，重建时次版本+补丁版本浮动
`floating`	`latest` , `main` , `master` , `edge` , `stable`	不佳——不可复现
`implicit-latest`	无标签	不佳——等效于 `:latest`
`custom`	其他情况	需要手动检查

运行时字段：

```
node_container
```
/
```
python_container
```
— 从Dockerfile的
```
FROM
```
行推断（容器实际运行的环境）
```
node_repo
```
/
```
python_repo
```
— 从
```
.nvmrc
```
/
```
.python-version
```
推断（开发工具预期的环境）

node_engine

python_requires

— 从

package.json

pyproject.toml

获取的显式约束

常见风险信号：

node_container=18

而

node_repo=22

意味着开发环境与容器运行环境的主版本不一致。