跳到主要内容
版本：0.1.x

LinaPro项目提供了一套跨平台开发指令集。长期维护的任务编排集中在hack/tools/linactl中，以Go程序实现；根目录Makefile和make.cmd只是兼容入口，都会转发到底层linactl。因此同一套命令可以在macOS、Linux和Windows上使用，不再依赖GNU Make或POSIX Shell作为唯一入口。

平台说明​

跨平台原生命令：所有平台都可以直接使用linactl：

cd hack/tools/linactl
go run . help
go run . status
go run . init confirm=init
go run . dev

macOS / Linux：可以继续使用根目录make兼容入口：

make help
make init confirm=init
make dev

Windows cmd.exe：使用项目根目录的make.cmd包装入口。在cmd.exe中会按可执行文件扩展名查找当前目录脚本，因此可直接省略.cmd后缀：

make dev
make build
make help

Windows PowerShell：需要加当前目录前缀。默认Windows环境下可写成.\make；如需避免与本机已安装的其他make命令混淆，可显式使用.\make.cmd：

.\make help
.\make init confirm=init
.\make dev

后续文档中所有make <指令>示例，都可以等价替换为cd hack/tools/linactl && go run . <指令>，参数格式保持一致。

指令总览​

指令分类说明
make dev.setup开发服务安装前端依赖和Playwright浏览器
make dev开发服务重启前后端开发服务器
make stop开发服务停止前后端开发服务器
make status开发服务查看前后端运行状态及日志路径
make build构建完整构建前端、插件和后端二进制
make pack.assets构建准备主框架嵌入所需的前端静态资源和manifest
make wasm构建构建所有或指定运行时WASM插件
make tidy构建整理主框架、工具和插件相关Go模块依赖
make image镜像构建生产Docker镜像
make image.build镜像仅准备镜像产物，不执行Docker构建
make test测试运行完整E2E测试套件
make test.go测试运行Go单元测试
make test.host测试只运行主框架自有E2E测试
make test.plugins测试运行官方插件自有E2E测试
make test.scripts测试运行工具脚本的单元与smoke测试
make i18n.check国际化扫描运行时硬编码文案并校验语言包key覆盖
make plugins.init插件工作区将官方插件子模块转换为普通目录
make plugins.install插件工作区安装配置中的源码插件到apps/lina-plugins
make plugins.update插件工作区更新apps/lina-plugins中的源码插件
make plugins.status插件工作区查看源码插件工作区状态
make init数据库初始化数据库表结构和种子数据
make mock数据库加载演示Mock数据
make release.tag.check发布治理校验release tag与metadata.yaml中framework.version一致
make help其他查看所有可用指令

开发服务​

make dev.setup​

安装开发与E2E测试所需的全部前置依赖，包括前端npm包和Playwright浏览器。在首次克隆仓库或CI环境初始化时执行一次即可，后续不需要重复运行。

make dev.setup

make dev​

重启后端和前端开发服务器。执行前会先停止已有服务，依次完成WASM插件构建、前端静态资源准备和后端编译，等待两端健康检查通过后打印运行状态。支持通过skip_wasm=true跳过WASM构建步骤以加快启动速度。

make dev

# 跳过 WASM 插件构建（适用于不涉及动态插件的开发场景）
make dev skip_wasm=true

后端默认监听http://localhost:8080，前端默认监听http://localhost:5666。运行日志分别写入temp/lina-core.log和temp/lina-vben.log。

make stop​

停止后端和前端开发服务器，并清理残留PID文件。对于仍占用端口的僵尸进程，会强制终止。

make stop

make status​

打印前后端当前的运行状态及日志文件路径，便于快速确认服务是否正常启动。

make status

输出示例：

+----------+---------+------------------------+-------+------------------------+--------------------+
| Service  | Status  | URL                    | PID   | PID File               | Log File           |
+----------+---------+------------------------+-------+------------------------+--------------------+
| Backend  | running | http://127.0.0.1:8080/ | 87739 | temp/pids/backend.pid  | temp/lina-core.log |
| Frontend | running | http://127.0.0.1:5666/ | 87740 | temp/pids/frontend.pid | temp/lina-vben.log |
+----------+---------+------------------------+-------+------------------------+--------------------+

构建​

make build​

完整构建流程，依次执行：前端静态资源构建、嵌入到后端的manifest资源准备、所有WASM插件构建，最后编译后端主框架二进制。构建产物输出到temp/output/目录。

# 默认构建（当前平台）
make build

# 指定目标平台（交叉编译）
make build platforms=linux/amd64,linux/arm64

# 开启详细日志
make build verbose=1
# 或
make build v=1

构建行为的默认值由仓库根目录的hack/config.yaml集中管理，命令行参数会覆盖文件中的对应字段。

build:
  # 目标平台列表，使用goos/goarch格式，make build platforms=...可覆盖
  platforms:        
    - "auto"
  # 是否启用 CGO
  cgoEnabled: false 
  # 构建产物输出路径，相对于仓库根目录
  outputDir: "temp/output" 
  # 编译后生成的二进制文件名
  binaryName: "lina"
字段默认值说明
build.platforms["auto"]目标平台列表，使用goos/goarch格式，auto表示linux/<当前架构>，make build platforms=...可覆盖
build.cgoEnabledfalse是否启用CGO
build.outputDirtemp/output构建产物输出路径，相对于仓库根目录
build.binaryNamelina主框架二进制文件名

make wasm​

单独构建运行时WASM插件。make wasm是兼容入口，默认把产物输出到temp/output/，支持使用p=<plugin-id>只构建指定插件。需要覆盖输出目录或只做构建探测时，直接使用linactl wasm。

# 构建所有 WASM 插件
make wasm

# 只构建指定插件（plugin-id 为插件目录名）
make wasm p=my-plugin

make pack.assets​

准备主框架manifest资产，用于Go嵌入，通常由make build或make dev自动调用。需要单独检查或准备嵌入资源时可以手动执行：

make pack.assets

make tidy​

整理主框架、开发工具和插件相关Go模块依赖，适合在升级依赖或初始化插件完整模式后执行：

make tidy

镜像​

make image​

完整的Docker镜像构建流程：先执行make build生成所有构建产物，再调用hack/tools/image-builder封装成镜像。镜像名称、标签、镜像仓库地址等均通过参数配置。

# 使用默认配置构建镜像
make image

# 指定标签和镜像仓库
make image tag=v0.6.0 registry=ghcr.io/linaproai

# 构建后直接推送
make image tag=v0.6.0 registry=ghcr.io/linaproai push=1

# 多平台构建
make image platforms=linux/amd64,linux/arm64 tag=v0.6.0

镜像构建的默认值同样由hack/config.yaml管理，命令行参数可覆盖本次执行。

image:
  # 镜像名称，构建时拼接 registry 前缀
  name: "linapro"       
  # 默认标签，留空时根据 git 信息自动推导             
  tag: "dev"  
  # 远端仓库前缀，例如 ghcr.io/linaproai                       
  registry: ""        
  # 是否默认推送，push=1 可覆盖本次执行               
  push: false      
  # 运行时基础镜像                  
  baseImage: "alpine:3.22"         
  # Dockerfile 路径，相对于仓库根目录  
  dockerfile: "hack/docker/Dockerfile"
字段默认值说明
image.namelinapro镜像名称，构建时会在前面拼接registry前缀
image.tagdev默认标签，留空时根据git信息自动推导
image.registry空远端仓库前缀，例如ghcr.io/linaproai
image.pushfalse是否默认推送，命令行push=1可覆盖本次执行
image.baseImagealpine:3.22运行时基础镜像
image.dockerfilehack/docker/DockerfileDockerfile路径，相对于仓库根目录

make image.build​

仅准备镜像构建的所有产物（等价于先执行make build），不执行Docker build步骤。适用于需要手动检查产物或自定义镜像构建步骤的场景。

make image.build

测试​

make test​

运行完整的Playwright E2E测试套件。执行前请确保开发服务已通过make dev启动。支持通过scope参数缩小测试范围：

scope值说明
full（默认）运行全部E2E测试
host仅运行主框架自有测试
plugins仅运行所有官方插件测试
plugin:<id>仅运行指定插件测试
make test

# 只运行主框架测试
make test scope=host

# 只运行指定插件测试
make test scope=plugin:multi-tenant

make test.go​

运行所有受维护Go模块的单元测试，并启用竞态检测。支持通过plugins=0强制主框架模式，或通过race=false关闭竞态检测。

make test.go
make test.go plugins=0
make test.go race=false

make test.host​

只运行主框架自有Playwright E2E测试，不要求初始化官方插件子模块。

make test.host

make test.plugins​

运行官方插件自有Playwright E2E测试，执行前需要先初始化apps/lina-plugins/子模块。

make test.plugins

make test.scripts​

运行跨平台仓库工具的单元和smoke检查，用于验证linactl、make.cmd等辅助入口的基本正确性。

make test.scripts

国际化​

make i18n.check​

扫描运行时可见的代码路径，检测未被纳入国际化体系的硬编码文案，并校验主框架和各插件运行时语言包的消息key覆盖情况。适合在提交新功能前进行i18n合规自查。

make i18n.check

插件工作区​

apps/lina-plugins/目录用于存放官方插件，既可以是Git submodule，也可以通过插件工作区命令管理为源码插件。以下命令提供对插件工作区的完整生命周期管理：

make plugins.init​

将apps/lina-plugins从Git submodule转换为普通插件目录，同时保留插件代码。转换后可以自由修改插件代码并提交变更，不再受submodule约束。

make plugins.init

make plugins.install​

根据hack/config.yaml中的plugins.sources配置，将远端插件仓库中的指定插件克隆到apps/lina-plugins/。支持通过p=<plugin-id>只安装一个插件，通过source=<name>只处理指定来源。

# 安装所有配置的源码插件
make plugins.install

# 只安装指定插件
make plugins.install p=multi-tenant

# 强制覆盖已存在的插件目录
make plugins.install force=1

make plugins.update​

更新apps/lina-plugins/中已配置的源码插件，拉取远端最新版本。有本地未提交改动的插件会被阻止更新，除非传入force=1。

make plugins.update
make plugins.update p=multi-tenant
make plugins.update force=1

make plugins.status​

查看当前官方插件工作区状态，包括已配置的插件版本、本地变更和远端更新情况。

make plugins.status

数据库​

破坏性操作

init和mock均会对数据库执行破坏性操作，因此要求显式传入confirm参数才能执行，防止误操作。

make init​

初始化数据库的表结构（DDL）和系统必需的种子数据。后端会按config.yaml中database.default.link的配置自动选择PostgreSQL或SQLite方言，其中PostgreSQL 14+是默认数据存储，SQLite仅用于本地演示或冒烟验证。

# 仅初始化（保留现有数据）
make init confirm=init

# 重建数据库（清空后重新初始化）
make init confirm=init rebuild=true

make mock​

在make init完成之后，加载用于本地演示和开发验证的可选Mock数据。

make mock confirm=mock

其他​

make help​

打印根Makefile及所有引入目标文件中的可用指令列表，输出按指令名称排序。

make help