Amplication data-service-generator-catalog 服务部署指南：环境变量、启动脚本与源码架构解析

Amplication contenteditable="false">【免费下载链接】amplicationAmplication brings order to the chaos of large-scale software development by creating Golden Paths for developers - streamlined workflows that drive consistency, enable high-quality code practices, simplify onboarding, and accelerate standardized delivery across teams.项目地址: https://gitcode.com/GitHub_Trending/am/amplication本文是 Amplication 仓库中data-service-generator-catalog服务位于 packages/data-service-generator-catalog的完整技术指南。它是一套由 Amplication 生成的后端服务组件负责代码生成器的版本目录与发布管理对外提供 REST/GraphQL API、认证授权、日志与数据库连接等能力。读完本文你将掌握该服务的全部环境变量配置、本地开发与容器化启动流程并能从源码层面理解其引导过程、模块组织与版本同步机制。服务定位代码生成器的版本目录data-service-generator-catalog是 Amplication 生态中一个独立的 NestJS 服务。从 README.md 的说明来看它承载着生成项目的服务端职责REST API、GraphQL API、认证、授权、日志、数据校验以及数据库连接。与仓库中的data-service-generator负责实际生成代码不同catalog 服务的核心职责从源码结构中清晰可见——它维护着**代码生成器Generator与其版本Version**的目录关系prisma/schema.prisma 中定义了Generator与Version两个模型Version通过generatorId外键关联到Generator并以unique([name, generatorId])约束同一生成器下版本名的唯一性src/version/version.service.ts 实现了版本查询、排序、选取与 AWS ECR 同步的完整逻辑src/generator 目录提供生成器资源的 CRUD 能力。从源码结构看该服务还通过 src/aws/aws-ecr.service.ts 直接对接 AWS ECRElastic Container Registry把容器镜像仓库中的镜像标签同步为数据库中的版本记录这使其成为生成器镜像发布与消费之间的目录中枢。第一步环境变量配置服务配置通过环境变量提供既可以注入到运行环境中也可以通过服务根目录下的.env文件传入。README 指出以下变量是生成后默认存在的变量通过插件扩展时可能会引入额外变量生成时已填充默认值请按需修改。变量说明默认值BCRYPT_SALT用于哈希的字符串[随机字符串]COMPOSE_PROJECT_NAME服务标识符加前缀amp_[服务标识符]PORT服务运行的端口3000DB_URL数据库连接 URL[db-provider]://[username]:[password]localhost:[db-port]/[db-name]DB_PORT数据库实例使用的端口[db-provider-port]DB_USER连接数据库的用户名[username]DB_PASSWORD连接数据库的密码[password]DB_NAME数据库名称[service-name] / [project-name]JWT_SECRET_KEY用于签名 JSON Web Token 的密钥[secret]JWT_EXPIRATIONJSON Web Token 的过期时间2d注意Amplication 会生成默认值并存储到.env文件中。生产环境建议使用某种形式的密钥管理secrets manager/vault方案。关键变量的源码级印证DB_URL在 prisma/schema.prisma 中数据源直接声明为url env(DB_URL)即 Prisma Client 完全依赖该变量建立 PostgreSQL 连接provider postgresql。JWT_SECRET_KEY / JWT_EXPIRATIONsrc/constants.ts 定义了JWT_SECRET_KEY_PROVIDER_NAME JWT_SECRET_KEY与JWT_EXPIRATION JWT_EXPIRATION两个常量名src/auth/jwt/jwtSecretFactory.ts 目录下的工厂逻辑会从配置/密钥管理中读取该值用于签发与校验 JWT。PORTsrc/main.ts 通过const { PORT 3000 } process.env读取端口缺省 3000而 Dockerfile 中容器内则设置ENV PORT3005并EXPOSE 3005说明容器场景下端口会以构建配置为准。JWT_EXPIRATION默认2d即令牌默认有效期为两天可按安全策略收紧或放宽。其他可用的运行时配置虽然不在 README 的默认表中src/app.module.ts 显示服务还支持一组 GraphQL 相关环境变量GRAPHQL_SCHEMA_DESTschema.graphql 输出路径缺省为src/schema.graphqlGRAPHQL_DEBUG设为1开启调试PLAYGROUND_ENABLE设为1同时开启 GraphQL Playground 与 introspectionDEV_VERSION_TAG由 src/version/version.service.ts 读取用于注入最新开发版本占位记录在版本选择策略中拥有最高优先级。第二步 1脚本执行前的环境准备配置完成后即可运行应用。运行服务端前请先确认以下前置条件已满足Node.js16.x 及以上npmDocker前置环境就绪后安装依赖并生成 Prisma Client# 安装依赖 $ npm install # 生成 prisma client $ npm run prisma:generateprisma:generate依据 prisma/schema.prisma 中的 generator 配置将客户端输出到./generated-prisma-client并声明了native、debian-openssl-1.1.x、linux-arm64-openssl-1.1.x多个二进制目标兼顾本地与容器运行环境。第二步 2本地开发启动# 启动服务将要连接的数据库 $ npm run docker:dev # 初始化数据库 $ npm run db:init # 启动服务端 $ npm run start默认情况下应用自带一个初始用户用户名为admin密码为admin。启动后的完整引导流程可以在 src/main.ts 中观察到通过Tracing.init来自amplication/util/nestjs/tracing初始化分布式追踪服务名取自 src/constants.ts 的data-service-generator-catalogNestFactory.create(AppModule, { cors: true })创建应用并开启 CORSapp.setGlobalPrefix(api)为所有 HTTP 路由统一添加/api前缀注册全局ValidationPipetransform: true负责请求数据校验与类型转换生成 Swagger 文档并对标记了isPublic的路由去除安全声明对应 src/decorators/public.decorator.ts从而允许匿名访问公开接口调用connectMicroservicessrc/connectMicroservices.ts与startAllMicroservices启动微服务连接在swaggerPath挂载 Swagger UI注册全局HttpExceptionFilter异常过滤器最后app.listen(PORT)。服务启动后同时暴露两类接口层REST 控制器如 src/version/version.controller.ts、src/generator/generator.controller.ts与 GraphQL Resolver如 src/version/version.resolver.ts二者由 src/app.module.ts 统一装配并叠加 src/auth/acl.module.ts 的访问控制ACL能力。第二步 3基于容器的开发启动# 以 docker 容器方式启动服务端 $ npm run compose:up容器化路径对应的产物定义在 Dockerfile 中基于node:18.13.0-slim镜像仅复制dist/packages/data-service-generator-catalog构建产物并执行npm install --production只安装生产依赖临时安装openssl以满足 Prisma 运行需求创建非特权用户uid/gid 默认 1001并以该用户运行遵循最小权限原则容器内默认端口 3005启动命令为node ./main.js。源码深挖版本目录的幕后机制版本选择策略src/version/version.service.ts 的getCodeGeneratorVersion是目录服务的核心方法支持三种由 amplication/code-gen-types 定义的CodeGeneratorVersionStrategySpecific按指定版本号精确匹配未命中或缺少codeGeneratorVersion时抛出BadRequestExceptionLatestMinor解析出指定版本的主版本号再在同主版本下挑选最新的次要版本getLatestMinorVersion找不到时抛出错误LatestMajor默认直接返回活跃版本列表中的最新版本getLatestVersion。版本排序由sortVersionssrc/version/version.service.ts实现它会剥离去掉v前缀按点分数字逐段比较。若配置了DEV_VERSION_TAG则开发版本优先于一切策略被返回。与 AWS ECR 的版本同步syncVersionssrc/version/version.service.ts展示了目录如何从镜像仓库刷新版本查询所有活跃生成器调用 src/aws/aws-ecr.service.ts 的getTags通过DescribeImagesCommand拉取镜像仓库中匹配正则/v\d\.\d\.\d/的标签默认仓库名为data-service-generator并自动翻页将新标签写入Version表把已不存在的旧版本标记为deletedAt、isActive: false、isDeprecated: true全程通过AmplicationLogger记录同步开始、成功与失败信息。配合 src/aws/aws-ecr.service.ts 的getGeneratorImages按generator-前缀枚举仓库可以推断出每个生成器镜像对应一个 ECR 仓库其镜像标签即版本号catalog 服务负责把镜像即版本的发布模型落库并提供给上层查询。数据模型与健康检查数据库模型非常精简prisma/schema.prisma 仅包含三张表User内置用户username唯一、roles为 JSON对应 README 中admin/admin的初始账号Generator生成器实体fullName与name唯一isActive默认falseVersion版本实体isActive、isDeprecated、deletedAt等字段支撑上文提到的版本生命周期管理。服务还提供了 src/health 健康检查模块含 src/health/health.controller.ts 与其基础实现用于探活与容器编排场景的就绪检测。总结data-service-generator-catalog的部署链路非常典型环境变量尤其是DB_URL与JWT_SECRET_KEY决定运行时行为npm installprisma:generate完成依赖与客户端准备docker:devdb:initstart支撑本地开发compose:up支撑容器化运行。而在表面配置之下它通过 Prisma NestJS 提供了生成器/版本目录的 CRUD 与查询 API并通过 AWS ECR 同步机制把镜像标签自动转化为版本元数据是 Amplication 代码生成流水线中连接镜像发布与版本消费的关键服务。如需进一步深入可以继续阅读同仓库中与其协作的 packages/data-service-generator实际代码生成器与 libs/util/code-gen-types版本策略等类型定义。【免费下载链接】amplicationAmplication brings order to the chaos of large-scale software development by creating Golden Paths for developers - streamlined workflows that drive consistency, enable high-quality code practices, simplify onboarding, and accelerate standardized delivery across teams.项目地址: https://gitcode.com/GitHub_Trending/am/amplication创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考