Infisical 基本使用

创建项目

1> 点击 “+ Add New Project”

2>. 选择“Secrets Management”

项目类型说明：

- Secrets Management(秘密管理)：用于存储、管理和同步环境变量（如数据库密码、API Key、Jwt Secret 等）;

- Certificate Manager (证书管理)： 管理 SSL/TLS 证书，并支持自动推送到 Nginx 或云平台;

- KMS (密钥管理服务)： 用于管理原始的加解密密钥（类似 AWS KMS），如果要在代码里手动做数据加密（Encrypt/Decrypt），会用到这个；

- Secret Scanning (密钥扫描)： 用于自动扫描 GitHub/GitLab 代码库，防止有程序员不小心把密码写死在代码里并提交了；

- PAM (特权访问管理)： 针对服务器 SSH、数据库账号等动态权限的管理；

- Agent Sentinel： 用于增强身份认证的安全监控（通常与 Machine Identity 配合使用）；

添加密钥 (Secrets)

1>. 选择显示所有环境；然后点击添加秘钥。

2>. 选择要添加的秘钥用于哪个环境（Development 开发环境, Staging 预发或测试环境, Production 生产环境）

安装 Infisical CLI

scoop bucket add org https://github.com/Infisical/scoop-infisical.git
scoop install infisical

在业务项目中使用

1>. 登录与初始化：

## 登录infisical
infisical login --domain http://infisical服务器地址

## 在业务项目（spring-boot）根目录执行如下命令，进行关联
infisical init  

infisical init  命令的作用将本地项目目录与 Infisical 平台上的特定项目进行关联；具体操作如下：

- 创建配置文件：在当前项目根目录下生成一个名为 infisical.json 的配置文件； 该文件包含了将本地代码库链接到 Infisical 远程项目所需的元数据（如项目 ID 等）；

- 建立关联：通过该命令，你可以选择或指定要同步的环境变量所属的 Infisical 项目；

- 后续基础：在本地开发环境中使用 Infisical 的关键步骤，完成初始化后才能使用 infisical run 等命令将配置好的机密（Secrets）注入到应用程序的运行环境中；

2>. 配置秘钥占位符

在 application.yml 中，使用在 infisical 中添加的秘钥的 key 做占位符：

spring:
  datasource:
    password: ${DB_PASSWORD}

3>. 启动项目

使用 infisical CLI 包裹启动命令，infisical 就会将密钥注入到 ENV 中

## 使用 Maven 启动项目
infisical run -- ./mvnw spring-boot:run

## 使用 Java 虚拟机运行一个打包好的可执行 JAR 文件
infisical run -- java -jar target/your-app.jar

在 VS Code 中启动项目

1>. 启动方式

在 VS Code 中启动项目的方式有如下两种：

方式一：打开 UserApplication.java 入口文件，在右上角点击“Run Java”启动。这是 VS Code 基础 Java 扩展（Debugger for Java / Language Support for Java）提供的原生功能。这种方式仅仅是把当前包含 main 方法的类当作一个普通的 Java 程序来执行。但它会去检查 .vscode/launch.json 中是否有匹配的运行配置；如果没有，就使用默认的最简参数直接调用 java 命令启动，否则就按 .vscode/launch.json 中的运行配置启动；此方式 纯粹、轻量，仅关注 Java 进程本身的启动和调试。

方式二：在 spring boot dashboard 中点击“Run”启动。这是由 Spring Boot Tools 相关插件提供的功能。它将项目识别为一个 Spring Boot 应用进行启动。在启动的同时或之后，Dashboard 会尝试与 Spring Boot 进程建立连接（通常依赖 Spring Boot Actuator 或 JMX），并提供应用监控能力；例如：实时查看所有已注册的 Beans、Controller 的路由映射 (Request Mappings)、当前生效的环境变量和实时的内存消耗等。如果是多模块服务，还可以很方便地统一管理它们的启停。这种方式启动时，也会去检查和使用 .vscode/launch.json 中的运行配置。

综上，在 VS Code 中无论通过哪种方式启动 spring 项目，其都会应用 launch.json 中的配置；launch.json 的配置内容如下：

{
  "configurations": [
    {
      "type": "java",
      "name": "Spring Boot-UserApplication<user>",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "mainClass": "cn.sidoc.user.UserApplication",  ## 启动类，即入口文件
      "projectName": "user", 
      "args": "",
      "envFile": "${workspaceFolder}/.env",  ## 环境变量文件位置
      "preLaunchTask": "export-infisical-env" ## 在启动 Java 进程前，先执行一个名为 export-infisical-env 的任务，任务定义在 .vscode/tasks.json 中
    }
  ]
}

.vscode/tasks.json  任务定义如下：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "export-infisical-env",
      "type": "shell",
      "command": "infisical export --format=dotenv > .env",
      "problemMatcher": [],
      "presentation": {
        "reveal": "silent",
        "panel": "shared",
        "clear": true
      }
    }
  ]
}

也就说，在 VS Code 无论通过何种方式启动项目，Vs Code 都会先执行 launch.json 配置；而 launch.json 中的上述配置让项目与 Infisical 无缝结合，具体如下：

① 先执行 preLaunchTask 任务，在任务中通过 infisical export --format=dotenv > .env 命令将 infisical 中的秘钥导出的项目根目录下的 .evn 文件中；

② envFile 加载上一步生成的 .env 文件到当前启动的 java 项目的环境变量中

③ 启动 Spring Boot 主类

Spring Boot 启动时，在 application.yaml 配置中读到 ${DB_URL} 这种占位符时，就会以 DB_URL 为 key ，依次去 命令行参数 (--DB_URL=xxx)、JVM 参数 (-DDB_URL=xxx)、系统环境变量 (System.getenv)等中去找这个占位符的值，最终在环境变量中找到并填充到配置中。

注：上述方案中，秘钥在 .env 文件中落盘，因此并不是开发环境下 infisical 应用的最佳实践，但已经是开发环境下平衡复杂度和安全性的最优解了。

开发环境下的数据库等资源本身就在本地，被攻击的概率不大，且就算被攻击也并不重要。

Spring Boot 集成 Infisical 总结

1>. Infisical 在生产环境中的集成并不是通过修改 Dockerfile，而是在容器启动阶段，通过 machine identity 获取短期凭证，并将密钥以环境变量的方式注入到应用进程中。这种方式避免了密钥进入镜像或代码仓库，符合安全最佳实践。

2>. 在开发环境中，可以通过 infisical run 启动 Spring Boot 项目，Infisical 会在进程启动前将密钥注入为环境变量，Spring Boot 可以无感知读取。但这种方式导致 VS Code 无法直接管理该进程（Launch 模式失效）。

VS Code 无法直接管理的意思是指：默认情况下，在 VS Code 中点击“启动”时，VS Code (Launch) 启动 Java 进程，然后项目的调试、停止、重启全由 VS Code 控制；但如果使用 infisical run 启动项目，Java 进程的“父进程”变成了 infisical，而不是 VS Code； 因为 VS Code 没有“持有”这个 Java 进程，或者说 Java 进程完全脱离的 VS Code，所以 VS Code 中的“停止”、“重启”等按钮都会失效，关闭 VS Code ，Java 进程仍然能独立运行。

3>. 可以通过 tasks.json + Attach 调试的方式集成 Infisical：此方式阻止 VS Code 启动 Java 进程，转而使用 infisical run 命令启动，同样也会导致 VS Code 无法直接管理 Java 进程；但此方式通过让 VS Code 连接到 JVM 的 debug 端口，从而能够实现在 VS Code 中调试 Java 程序的目的。

4>. VS Code 在启动 Java 前，会先读取 launch.json，并按需执行 preLaunchTask 中的命令(如果有配置)，然后启动 JVM。VS Code 支持通过 envFile（文件）向 Java 进程注入环境变量，但这些变量必须在 Java 进程启动前以静态方式确定；因此要将密钥写入 launch.json 或 .env（秘钥落盘），然后让 VS Code 读取并注入到 Java 进程的环境变量中。

VS Code 启动 java 进程，意味着 java 进程是 VS Code 的子进程；子进程会随父进程销毁，也会继承父进程内存中的环境变量；因此，向 VS Code 中注入环境变量，然后让 Java 进程继承，也可以实现为 Java 进程注入环境变量的目的；但环境变量注入必须在进程启动前进行， VS Code 已经启动之后，就无法再注入环境变量了。VS Code 在启动 Java 前，会先读取 launch.json 配置，并按需执行命令；这些命令以 VS Code 子进程的方式执行，也就是与 Java 进程是兄弟进程，因此也无法在这些命令中给 Java 进程注入环境变量（只能父进程能给子进程注入环境变量）；况且在读取 launch.json 配置并执行命令时，Java 进程还不存在，没有可注入的地方。

5>. spring.config.import 方式：spring boot 项目在启动时可以执行自定义的 ConfigDataLoader 扩展代码，在扩展中通过 Infisical 动态获取秘钥，并添加到环境变量中 。此方式最大的问题就是要把 Infisical 的访问 token 写死在代码时，这会造成巨大的安全隐患，一旦 Infisical 的访问 token 泄漏，那 Infisical 中的秘钥将全部丢失。

最佳实践

1>. 开发环境

让 VS Code 启动 Java 项目前读取 launch.json 配置，然后执行 preLaunchTask 中的命令获取并落盘 infisical 中的秘钥；然后 VS Code 根据 launch.json 中的 envFile 配置读取，并将向秘钥注入到 Java 进程中。 即，秘钥先落盘为 .env 文件，然后在 envFile 配置 .env 文件的路径，再由 VS Code 读取 .env 文件中的内容，并在启动 Java 进程时注入。

注：.env 必须添加到 .gitignore，并禁止 AI 读取，同时在 .vscode/setting.json 中配置排除 .env 文件；

2>. 生产环境