本文详解 Rundeck 中通过文件类型选项（type: file）上传文件后，在 Python 脚本中安全获取其完整路径并读取内容（如用 pandas 加载 Excel/CSV），重点解决常见路径拼接错误与权限访问问题。
本文详解 rundeck 中通过文件类型选项（`type: file`）上传文件后，在 python 脚本中安全获取其完整路径并读取内容（如用 pandas 加载 excel/csv），重点解决常见路径拼接错误与权限访问问题。
在 Rundeck 中集成 Python 脚本处理用户上传的文件（如 Excel、CSV 或配置文件）是一项高频需求，但新手常因混淆“文件路径变量”与“实际存储位置”而失败。核心误区在于：Rundeck 的 ${file.XXX} 语法不直接返回文件绝对路径，而是返回 Rundeck 内部上传后的临时路径（如 /var/lib/rundeck/var/upload/uuid），且该路径需与文件名组合才能构成可访问的完整路径；同时，脚本执行环境（如 Rundeck 服务用户 rundeck）必须对目标路径有读取权限。
✅ 正确做法：使用 Script Step + 显式参数传递
Rundeck 推荐且最可靠的方式是采用 Script Step（而非 exec 命令行调用），它原生支持将选项值作为参数注入脚本，并自动处理路径解析与上下文隔离：
1. Rundeck Job 定义（YAML 示例）
- name: Process Uploaded File
description: Read uploaded Excel file with pandas in Python
sequence:
commands:
# Step 1: 可选 —— 打印调试信息确认变量值
- exec: echo "Upload path: ${file.history_path} | Filename: ${file.history_path.fileName}"
# Step 2: 关键！使用 Script Step 执行 Python 脚本
- args: "${file.history_path} ${file.history_path.fileName}"
scriptInterpreter: /opt/env/bin/python
scriptfile: /opt/script/main.py
interpreterArgsQuoted: false
expandTokenInScriptFile: true
fileExtension: .py⚠️ 注意事项：
- args 字段中使用双引号包裹 ${...} 变量，确保空格和特殊字符被正确传递；
- scriptfile 必须指向服务器上已存在的、具有执行权限的 Python 脚本（非内联代码）；
- interpreterArgsQuoted: false 表示参数不额外加引号（避免 "/path" "/name" 变成 ""/path"" ""/name""）；
- expandTokenInScriptFile: true 允许脚本内继续使用 Rundeck 变量（如需动态构造日志路径等）。
2. Python 脚本（main.py）健壮实现
#!/usr/bin/env python3
import os
import sys
import pandas as pd
def main():
if len(sys.argv) < 3:
raise ValueError("Usage: python main.py <upload_path> <filename>")
upload_dir = sys.argv[1].strip()
filename = sys.argv[2].strip()
# ✅ 正确拼接：Rundeck 上传后文件位于 upload_dir 下，filename 即其原始名称
full_path = os.path.join(upload_dir, filename)
print(f"[DEBUG] Upload directory: {upload_dir}")
print(f"[DEBUG] Filename: {filename}")
print(f"[DEBUG] Full path resolved: {full_path}")
print(f"[DEBUG] Path exists: {os.path.isfile(full_path)}")
# ? 权限检查（生产环境强烈建议）
if not os.path.isfile(full_path):
raise FileNotFoundError(f"File not found at: {full_path}")
if not os.access(full_path, os.R_OK):
raise PermissionError(f"No read permission on: {full_path}")
# ? 示例：用 pandas 读取 Excel 文件
try:
df = pd.read_excel(full_path)
print(f"✅ Successfully loaded {len(df)} rows from {filename}")
print(df.head())
except Exception as e:
print(f"❌ Failed to process file: {e}")
raise
if __name__ == "__main__":
main()3. 关键原理说明
| 概念 | 说明 | 常见错误 |
|---|---|---|
| ${file.XXX} | 返回 Rundeck 服务端上传后的临时目录路径（如 /var/lib/rundeck/var/upload/abc123），不是客户端路径 | 误以为是本地路径或工作目录下的相对路径 |
| ${file.XXX.fileName} | 返回用户上传时的原始文件名（如 data.xlsx），不含路径 | 直接传给 open() 导致 FileNotFoundError |
| os.path.join(upload_dir, filename) | 唯一可靠的拼接方式，生成真实可访问路径 | 错误拼接为 upload_dir + "/" + filename（未处理跨平台路径分隔符） |
4. 生产环境必备检查清单
- ✅ 权限验证：确保 rundeck 用户对 /var/lib/rundeck/var/upload/ 及其子目录有 r-x 权限；
- ✅ 磁盘空间监控：Rundeck 默认保留上传文件 7 天，大文件需定期清理或配置 rundeck.storage.converter.upload.cleanupAge=1d；
- ✅ 文件类型校验：在 Python 中增加 mimetypes.guess_type(full_path) 或 python-magic 防止恶意文件上传；
- ✅ 超时设置：若文件较大（>50MB），在 Job 中设置 timeout: 600s 避免任务中断；
- ✅ 日志脱敏：避免在日志中打印完整路径或敏感文件名（尤其审计场景）。
通过 Script Step 显式传递路径与文件名，配合 Python 端严谨的路径拼接与权限校验，即可稳定实现 Rundeck 文件上传 → Python 解析 → 业务逻辑处理的全链路闭环。此方案兼容 Rundeck 3.4+ 至最新 5.x 版本，是官方推荐的最佳实践。
立即学习“Python免费学习笔记（深入）”；
