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` 启动。

**结果**: 失败。
**错误日志**:

```text
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 清理进程

执行以下命令释放端口：

```bash
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。
**本地验证结果**:

```bash
# 构建
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 等待自动构建。

```bash
export N8N_PORT=7860 && npx n8n start
```

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

```text
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` 或具体版本号。

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