安装和配置 IaC Code

更新时间:
复制 MD 格式

本文说明 IaC Code 的公共安装和配置流程,包括 Python 环境、Windows Git Bash、可选依赖、模型服务和阿里云身份。完成后,REPL、Headless、Web 和协议服务可以复用同一份配置。

前提条件

项目

要求

Python

3.10 或更高版本。建议使用与项目隔离的虚拟环境。

操作系统

macOS、Linux 或 Windows。

大模型服务

一个 IaC Code 支持的大模型服务及其访问凭据。

阿里云身份

本地方案设计或文件处理时可选;查询或管理云资源时需要。

Windows 附加要求

Git for Windows 提供工具执行所需的 Git Bash。

安装软件包时不需要提供模型或阿里云凭据。示例中不要填写真实 API Key、AccessKey Secret 或访问令牌。

安装基础包

运行以下命令:

python -m pip install iac-code

验证命令和版本:

iac-code --help
iac-code --version

预期结果:终端显示 IaC Code 的命令帮助和当前版本号。基础包支持 REPL、Headless 和 ACP Stdio 等核心能力。

在 Windows 上安装 Git Bash

如果尚未安装 Git for Windows,请在 PowerShell 或命令提示符中运行:

iac-code install-git-bash

该命令仅在 Windows 上提供,会通过 npmmirror 下载安装程序。按界面提示完成安装并允许必要的用户账户控制(UAC)操作。安装完成后,命令会重新检测 bash.exe 并输出路径。

快捷安装受企业网络策略限制时,可以改用:

winget install --id Git.Git -e --source winget

也可以手动安装 Git for Windows。

安装可选能力

基础包之外的运行方式按需安装:

可选能力

安装命令

Web 版

python -m pip install "iac-code[http]"

A2A Server

python -m pip install "iac-code[a2a]"

AG-UI Server

python -m pip install "iac-code[agui]"

Web、A2A 和 AG-UI

python -m pip install "iac-code[http,a2a,agui]"

如果在缺少可选依赖时启动对应命令,IaC Code 会提示需要安装的 Extra。

配置模型和阿里云身份

模型配置用于访问大模型服务。阿里云身份用于查询云产品、规格、资源栈和账号内资源, 以及执行部署、更新或删除。

选择配置入口

配置入口

操作方式

适用场景

REPL

运行 iac-code,输入 /auth

已在终端工作,或准备使用 Headless、ACP、AG-UI、A2A

Web

打开“设置 > 模型”和“设置 > 云凭证”

希望在浏览器中完成可视化配置

两种入口写入相同的配置目录,不需要重复设置。Web 表单的完整操作请参见 使用 Web 版,REPL 的认证流程请参见 使用 REPL 交互模式。

选择阿里云认证方式

根据运行环境选择最小权限的认证方式:

认证方式

适用场景

OAuth 浏览器登录

本地交互使用,希望避免手动管理长期 AccessKey。

ECS RAM Role

IaC Code 运行在 ECS 实例上。

STS Token

自动化系统提供短期凭据。

RAM 角色

使用一个身份扮演目标 RAM 角色。

AccessKey

其他方式不适用时使用最小权限 RAM 用户的 AccessKey。

不要使用主账号长期 AccessKey。创建、更新和删除云资源所需权限应与只读查询权限分开管理。

配置文件和安全

默认配置目录为:

~/.iac-code/
├── .credentials.yml          # 大模型服务凭据
├── .cloud-credentials.yml    # 阿里云身份凭据
└── settings.yml              # 运行设置

通过环境变量 IAC_CODE_CONFIG_DIR 可以修改配置目录。其下的项目、会话、Skill、MCP、记忆和日志等运行数据也会随之迁移到新目录。

请遵循以下安全要求:

  • 不把凭据文件提交到代码仓库,不在命令、提示词或日志中打印真实密钥。

  • 限制配置目录和凭据文件的操作系统访问权限。

  • 自动化环境通过 Secret 管理服务注入短期凭据,不把密钥写入脚本。

  • 定期轮换凭据,并及时撤销不再使用的身份和权限。

升级和卸载

升级 IaC Code:

python -m pip install --upgrade iac-code

卸载 IaC Code:

python -m pip uninstall iac-code

卸载软件包不会主动删除 ~/.iac-code/ 下的配置和会话。清理目录前,请确认没有需要保留的凭据、会话或项目记录。

常见问题

找不到 iac-code 命令

确认安装命令使用的 Python 与当前终端环境一致,并检查 Python 脚本目录是否在 PATH 中。使用虚拟环境时,先激活环境,再运行 iac-code --help。

Windows 仍然提示找不到 Git Bash

先运行 iac-code install-git-bash。如果 Git for Windows 已安装但没有被识别,请在 PowerShell 中设置:

$env:IAC_CODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"

需要长期生效时,将相同配置保存为 Windows 用户环境变量。

模型认证失败

确认模型服务商、模型名、API Base URL 和 API Key 相互匹配,并检查企业代理和目标服务连通性。Web 用户还需确认已经将保存的配置设为当前模型。

阿里云操作提示无权限

确认认证方式、凭据有效期和地域正确,并为身份授予任务所需的最小 RAM 权限。不要通过硬编码主账号 AccessKey 绕过权限问题。

相关文档