ApiFlow Engine - 运维操作

Version: 0.1.0.alpha

运维操作

本节介绍以进阶部署为基础的日常运维操作和最佳实践。

`api` 命令完整参考

以下所有命令需在部署目录中执行（进阶部署模式）或 ApiFlow 系统目录中执行（快速体验/基础配置模式）。

命令	说明	示例
`api start`	前台启动服务	`api start`
`api start -d`	后台启动服务（守护进程模式）	`api start -d`
`api stop`	停止服务	`api stop`
`api status`	查看服务状态	`api status`
`api reload`	热重载所有工作流（无需重启）	`api reload`
`api check`	检查工作流语法是否正确	`api check`
`api -v`	显示版本信息	`api -v`
`api -h`	显示帮助信息	`api -h`

使用示例：

bash

# 在部署目录中执行
cd /opt/my-apiflow-deployment

# 启动服务（守护进程模式）
api start -d

# 检查服务状态
api status

# 修改工作流后热重载
api reload

# 检查工作流语法
api check

# 停止服务
api stop

自定义 JVM 启动参数

生产环境中，您可能需要自定义 JVM 内存大小、GC 策略等参数。推荐创建启动脚本来管理这些配置。

方式 1：使用环境变量（临时）

bash

# 设置 JVM 参数
export JVM_OPTS="-Xms1g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

# 设置 Spring Boot 参数
export SPRING_OPTS="--spring.profiles.active=prod"

# 启动服务
api start -d

方式 2：创建启动脚本（推荐）

在部署目录中创建 start.sh（Unix/Linux/macOS）：

bash

#!/bin/bash
# ApiFlow 生产环境启动脚本

# 设置工作目录
cd "$(dirname "$0")"

# JVM 参数配置
export JVM_OPTS="-Xms1g -Xmx4g \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=logs/heapdump.hprof \
  -Djava.security.egd=file:/dev/./urandom"

# Spring Boot 参数配置
export SPRING_OPTS="--spring.profiles.active=prod"

# 启动服务
api start -d

echo "ApiFlow started with PID: $(cat tmp/apiflow.pid)"

赋予执行权限并启动：

bash

chmod +x start.sh
./start.sh

JVM 参数推荐配置

bash

# 开发环境（小内存）
JVM_OPTS="-Xms256m -Xmx512m"

# 生产环境（中等负载）
JVM_OPTS="-Xms1g -Xmx4g -XX:+UseG1GC"

# 生产环境（高负载）
JVM_OPTS="-Xms4g -Xmx8g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 \
  -XX:+ParallelRefProcEnabled \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=logs/heapdump.hprof"

工作流项目升级和回滚

推荐方式：使用 Git 版本管理

进阶部署模式下，工作流项目独立于 ApiFlow 系统，适合用 Git 进行版本控制。

日志配置和管理

日志文件位置

默认日志文件位于部署目录的 logs/ 子目录：

logs/
├── apiflow.log        # 主应用日志（滚动归档）
├── apiflow-2024-12-17.log
├── apiflow-2024-12-16.log
└── startup.log        # 启动日志（守护进程模式）

日志级别调整

编辑 config/logback-spring.xml：

xml

<configuration>
    <!-- 设置 ApiFlow 核心日志级别 -->
    <logger name="org.apiFlow" level="INFO"/>

    <!-- 调试模式（输出更多信息） -->
    <!-- <logger name="org.apiFlow" level="DEBUG"/> -->

    <!-- 生产环境（减少日志输出） -->
    <!-- <logger name="org.apiFlow" level="WARN"/> -->

    <!-- Spring 框架日志 -->
    <logger name="org.springframework" level="WARN"/>

    <!-- SQL 日志（调试数据库问题时启用） -->
    <!-- <logger name="org.apiFlow.apps" level="DEBUG"/> -->
</configuration>

修改后需重启服务生效：

bash

api stop
api start -d

日志滚动归档配置

编辑 config/logback-spring.xml 中的滚动策略：

xml

<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
    <!-- 日志文件名格式 -->
    <fileNamePattern>logs/apiflow-%d{yyyy-MM-dd}.log</fileNamePattern>

    <!-- 保留 30 天日志 -->
    <maxHistory>30</maxHistory>

    <!-- 日志文件总大小上限（防止磁盘占满） -->
    <totalSizeCap>10GB</totalSizeCap>
</rollingPolicy>

监控和维护

ApiFlow 集成了 Spring Boot Actuator，提供丰富的监控和管理端点。

启用固定管理端口

重要： 生产环境必须将 management.server.port 设置为固定端口（默认为 0 随机端口）。

编辑 config/application.properties：

properties

# 固定管理端口
management.server.port=9090

# 启用的监控端点
management.endpoints.web.exposure.include=health,info,workflow,shutdown
management.endpoint.health.show-details=always
management.endpoint.shutdown.enabled=true

重启服务生效：

bash

api stop
api start -d

健康检查

bash

# 基础健康检查
curl http://localhost:9090/actuator/health

# 返回示例
{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 123456789012,
        "threshold": 10485760
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

集成到负载均衡/容器编排：

Kubernetes Liveness Probe:

yaml

livenessProbe:
  httpGet:
    path: /actuator/health
    port: 9090
  initialDelaySeconds: 30
  periodSeconds: 10

Nginx 健康检查:

nginx

upstream apiflow {
    server 127.0.0.1:8824 max_fails=3 fail_timeout=30s;
    check interval=5000 rise=2 fall=3 timeout=1000 type=http;
    check_http_send "GET /actuator/health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx http_3xx;
}

查看应用信息

bash

# 应用基本信息
curl http://localhost:9090/actuator/info

# 返回示例
{
  "app": {
    "name": "ApiFlow Engine",
    "version": "1.0.0",
    "description": "Event-driven workflow engine"
  }
}

查看工作流状态

bash

# 查看已加载的工作流列表
curl http://localhost:9090/actuator/workflow

# 返回示例
{
  "workflows": [
    {
      "name": "welcome",
      "path": "api/welcome.groovy",
      "triggers": ["webhook:/welcome"],
      "status": "active"
    },
    {
      "name": "daily-report",
      "path": "api/daily-report.groovy",
      "triggers": ["cron:0 0 9 * * ?"],
      "status": "active"
    }
  ]
}

与 Prometheus/Grafana 集成

参考官方文档创建仪表板：

故障排除

1. 服务无法启动

症状： 执行 api start 失败或服务启动后立即退出。

排查步骤：

bash

# 1. 检查 Java 版本
java -version
# 确保 >= Java 11

# 2. 检查配置文件是否存在
ls -la config/application.properties

# 3. 查看启动日志
tail -f logs/startup.log
tail -f logs/apiflow.log

# 4. 检查端口占用
lsof -i :8824        # 应用端口
lsof -i :9090        # 管理端口
# Windows: netstat -ano | findstr :8824

# 5. 手动启动查看详细错误
java -jar $APIFLOW_HOME/lib/apiFlow-server-1.0.0.jar \
  --spring.config.location=config/application.properties

常见原因：

❌ Java 版本过低（< 11）
❌ 配置文件路径错误或不存在
❌ 端口被占用
❌ project.home 路径不存在或无权限访问
❌ 磁盘空间不足

2. 运维命令失败（reload/status/stop）

症状： api reload、api status 等命令报错。

排查步骤：

bash

# 1. 确认服务正在运行
ps aux | grep apiFlow
# Windows: tasklist | findstr java

# 2. 检查管理端口文件
cat tmp/ops.port
# 应输出端口号如 9090

# 3. 手动测试管理端点
curl http://localhost:9090/actuator/health

# 4. 确认 curl 已安装
curl --version

# 5. 检查防火墙是否阻止本地连接

常见原因：

❌ 服务未启动或已崩溃
❌ management.server.port 配置为随机端口（0），导致端口变化
❌ curl 未安装或不在 PATH 中
❌ 防火墙阻止本地连接

解决方案： 将 management.server.port 设置为固定端口（如 9090）。

3. 工作流热重载失败

症状： 执行 api reload 后工作流未更新或报错。

排查步骤：

bash

# 1. 检查工作流语法
api check

# 2. 查看详细错误日志
tail -n 50 logs/apiflow.log | grep -i error

# 3. 验证工作流文件路径
ls -la workflow-project/api/

# 4. 检查文件权限
# 确保 ApiFlow 进程有读取权限

常见错误：

❌ Groovy 语法错误（缺少括号、引号等）
❌ DSL 结构错误（如在 start 块使用了非 DSL 代码）
❌ 工作流文件路径错误
❌ 文件编码问题（使用 UTF-8 编码）

日志示例：

ERROR o.a.c.FlowEngine - Failed to reload workflow: api/demo.groovy
Caused by: org.codehaus.groovy.control.MultipleCompilationErrorsException:
startup failed:
api/demo.groovy: 10: unexpected token: } @ line 10, column 1.

4. 端口冲突

症状： 启动时报错 Port 8824 was already in use。

解决方案：

bash

# 方式 1：停止占用端口的进程
lsof -i :8824
kill -9 <PID>

# 方式 2：修改配置使用其他端口
vim config/application.properties
# 修改 server.port=8825

5. 内存不足（OutOfMemoryError）

症状： 日志中出现 java.lang.OutOfMemoryError: Java heap space。

解决方案：

bash

# 增加 JVM 堆内存
export JVM_OPTS="-Xms2g -Xmx4g"
api stop
api start -d

# 或修改启动脚本（参考"自定义 JVM 启动参数"章节）

6. 工作流执行失败

症状： 访问工作流端点返回 500 错误或异常信息。

排查步骤：

bash

# 1. 查看实时日志
tail -f logs/apiflow.log

# 2. 访问工作流并观察日志输出
curl http://localhost:8824/api/your-workflow

# 3. 检查工作流中的外部依赖
# - 数据库连接配置是否正确
# - HTTP 请求的目标地址是否可达
# - 应用插件配置是否完整

常见原因：

❌ 数据库连接失败（账号密码错误、网络不通）
❌ HTTP 请求超时或目标服务不可用
❌ 应用插件未正确配置（检查 config.groovy）
❌ 工作流逻辑错误（空指针、类型转换等）

7. 日志文件过大导致磁盘占满

症状： 服务变慢或无法写入文件。

解决方案：

bash

# 1. 清理旧日志
cd logs
rm -f apiflow-2024-*.log

# 2. 调整日志保留策略
vim config/logback-spring.xml
# 修改 <maxHistory>30</maxHistory> 为更小的值

# 3. 降低日志级别
# 将 DEBUG 改为 INFO 或 WARN

8. 进程意外退出

症状： 后台启动的服务莫名停止。

排查步骤：

bash

# 1. 查看系统日志
# Linux
sudo journalctl -u apiflow
dmesg | tail

# macOS
tail -f /var/log/system.log

# 2. 检查是否 OOM Killer 杀死进程
dmesg | grep -i "out of memory"

# 3. 查看 JVM 崩溃日志
ls -la hs_err_pid*.log
cat hs_err_pid*.log

常见原因：

❌ 系统内存不足，进程被 OOM Killer 终止
❌ JVM 崩溃（bug、不兼容的 native library）
❌ 用户手动 kill -9

解决方案：

增加系统内存或减少 JVM 堆内存
升级 Java 版本
启用 HeapDump 分析内存泄漏

附录

系统要求

Java: Java 11 或更高版本
- 推荐使用 Java 11 LTS 或 Java 17 LTS
- Oracle JDK、OpenJDK、Azul Zulu、Amazon Corretto 均支持
curl: 用于运维命令（通常已预装）
- Unix/Linux/macOS 通常预装
- Windows 10 1803+ 已内置
操作系统:
- Unix/Linux（使用 api 脚本）
- macOS（使用 api 脚本）
- Windows（使用 api.cmd 脚本）

文件权限说明

确保以下目录可读写：

bash

chmod 755 bin/api                    # 可执行
chmod -R 755 config/                 # 可读
chmod -R 755 logs/                   # 可读写
chmod -R 755 tmp/                    # 可读写
chmod -R 755 workflow-project/       # 可读

支持和反馈

如有问题或建议，请访问：

项目主页：https://github.com/your-org/apiFlow-engine
问题跟踪：https://github.com/your-org/apiFlow-engine/issues
ApiFlow语法文档：doc/apiflow-dsl-skill/references/

许可证

请参阅项目根目录的 LICENSE 文件。

版本历史：

v0.1.0.alpha (2025-12-18)：初始版本

相关文档：

ApiFlow Engine - 运维操作 ​

运维操作 ​

api 命令完整参考 ​

自定义 JVM 启动参数 ​

方式 1：使用环境变量（临时） ​

方式 2：创建启动脚本（推荐） ​

JVM 参数推荐配置 ​

工作流项目升级和回滚 ​

日志配置和管理 ​

日志文件位置 ​

日志级别调整 ​

日志滚动归档配置 ​

监控和维护 ​

启用固定管理端口 ​

健康检查 ​

查看应用信息 ​

查看工作流状态 ​

与 Prometheus/Grafana 集成 ​

故障排除 ​

1. 服务无法启动 ​

2. 运维命令失败（reload/status/stop） ​

3. 工作流热重载失败 ​

4. 端口冲突 ​

5. 内存不足（OutOfMemoryError） ​

6. 工作流执行失败 ​

7. 日志文件过大导致磁盘占满 ​

8. 进程意外退出 ​

附录 ​

系统要求 ​

文件权限说明 ​

支持和反馈 ​

许可证 ​

ApiFlow Engine - 运维操作

运维操作

`api` 命令完整参考

自定义 JVM 启动参数

方式 1：使用环境变量（临时）

方式 2：创建启动脚本（推荐）

JVM 参数推荐配置

工作流项目升级和回滚

日志配置和管理

日志文件位置

日志级别调整

日志滚动归档配置

监控和维护

启用固定管理端口

健康检查

查看应用信息

查看工作流状态

与 Prometheus/Grafana 集成

故障排除

1. 服务无法启动

2. 运维命令失败（reload/status/stop）

3. 工作流热重载失败

4. 端口冲突

5. 内存不足（OutOfMemoryError）

6. 工作流执行失败

7. 日志文件过大导致磁盘占满

8. 进程意外退出

附录

系统要求

文件权限说明

支持和反馈

许可证