debug.md

n8n Local Testing & Debug Log

1. 测试环境 (Test Environment)

• OS: macOS
• Node: v22.17.0
• n8n Version: 2.1.2 (via npx)

2. 测试目标 (Objective)

验证 n8n 是否能在非默认端口 7860 (Hugging Face Spaces 标准端口) 正常启动。

3. 测试过程 (Testing Process)

3.1 初始尝试

直接使用 npx n8n start --port=7860 启动。

结果: 失败。 错误日志:

n8n's port 5678 is already in use.

分析: n8n 即使指定了 port，有时仍会检测默认端口或存在残留进程。

3.2 端口冲突排查

执行 lsof -i :5678 -i :7860 发现：

• 7860 端口被旧的 Python (Gradio) 进程占用。
• 5678 端口被之前的 n8n node 实例占用。

3.3 清理进程

执行以下命令释放端口：

kill -9 <Python_PID>  # 清理旧 Gradio
kill -9 <Node_PID>    # 清理旧 n8n 实例

3.4 最终验证

使用环境变量方式强制指定端口并启动：

5. HF Spaces 部署故障排查 (HF Spaces Troubleshooting)

5.1 报错：apk not found

现象: 在 HF Spaces 构建时提示 /bin/sh: apk: not found。 原因: n8nio/n8n:latest 的最新镜像基底是 Debian/Ubuntu，而非 Alpine。

5.2 解决方案：切换至 Node 基础镜像并手动安装 n8n

修复方式: 放弃使用 n8nio/n8n 官方镜像作为基底，改用标准的 node:22-alpine。在这种环境下，apk 是可用的，可以稳定安装 Python 3 和 n8n。 本地验证结果:

# 构建
docker build -t n8n-verified .

# 验证二进制版本
docker run --rm --entrypoint sh n8n-verified -c "n8n --version && python3 --version"
# 输出:
# 2.1.2
# Python 3.12.12

结论: 最终方案在本地 Docker 环境下完美运行，已推送到 HF Spaces 等待自动构建。

export N8N_PORT=7860 && npx n8n start

结果: 成功 (SUCCESS) 成功日志:

Initializing n8n process
n8n ready on ::, port 7860
n8n Task Broker ready on 127.0.0.1, port 5679
Registered runner "JS Task Runner"

4. 结论 (Conclusion)

• n8n 地支持通过 N8N_PORT 环境变量修改监听端口。
• 端口 7860 在本地及 HF Spaces 环境下均被证明可行。
• 核心配置文件 Dockerfile 和 README.md 已根据此验证结果完成适配。

5. HF Spaces 部署故障排查 (HF Spaces Troubleshooting)

5.1 报错：apk not found

现象: 在 HF Spaces 构建时提示 /bin/sh: apk: not found。 原因: n8nio/n8n:latest 的最新镜像基底是 Debian/Ubuntu，而非 Alpine。 修复: 最终方案切换至官方 n8nio/n8n:latest (Debian) 并使用 apt-get。

5.2 进一步简化：大道至简版

修复方式: 直接使用 FROM n8nio/n8n:latest。 验证结果: n8nio/n8n:latest-alpine 标签不存在（导致 404），必须使用 latest 或具体版本号。

FROM n8nio/n8n:latest
USER root
RUN apt-get update && apt-get install -y python3
USER node