部署并验收自动架构文档流水线
可易团队阅读约 7 分钟
本文给出部署架构文档流水线的前提、七步命令、监控告警与清理，并记录生产环境中的交付、恢复和上手变化。
目录
#部署并验收自动架构文档流水线
方案演练
本节带你在自己的 AWS 环境中部署该方案。我们涵盖前提条件、部署步骤和关键配置细节，以便让流水线针对你的代码库运行起来。
前提条件
部署该方案之前，请确认以下 AWS 服务已启用、权限已配置，并且具备相应的技术熟悉程度。
AWS 账户设置：确认你的 AWS 账户可以访问 Amazon Bedrock，并且在目标区域已启用 Claude Sonnet 和 Amazon Titan Text Embeddings v2（为保证模型可用性，建议使用 us-east-1）。
IAM 权限：为 AWS CodePipeline 创建一个 AWS IAM 角色，并具备以下权限：
- AWS CodeCommit 仓库访问。
- AWS CodeBuild 项目执行。
- AgentCore 调用。
- Amazon Bedrock Knowledge Bases 的 StartIngestionJob 和 Retrieve 操作。
- Amazon S3 存储桶读写访问（源代码、图表和向量存储桶）。
- Amazon CloudWatch Logs 创建。
- AWS Cloud Development Kit（AWS CDK） 引导：
cdk bootstrap aws://ACCOUNT_ID/us-east-1。
技术技能（300–400 级要求）：
- .NET 代码库： 你需要熟悉标准 .NET 项目结构和常见编码模式。
- CI/CD 流水线： 你需要基本理解自动化构建和部署流水线（最好是 AWS CodePipeline）。
- AWS CDK： 你需要有使用 AWS CDK 以代码部署基础设施的经验。
- 架构可视化： 你需要能够解读技术图和架构模式。
仓库结构：该方案最适合遵循标准 .NET 项目约定的代码库，源代码位于 src/ 目录，并且生产代码与测试代码清晰分离。
部署步骤
前提条件就绪后，按以下步骤部署端到端流水线。每一步都建立在上一步之上，因此请按顺序完成。
- 部署 AgentCore 智能体：使用 AgentCore CLI 打包智能体代码并部署到 AWS。
# Package the agent
agentcore package \
--agent-name architecture-diagram-agent \
--entry-point agent/main.py \
--requirements requirements.txt \
--output-dir ./build
# Deploy the agent to AgentCore
agentcore deploy \
--agent-name architecture-diagram-agent \
--package ./build/agent.zip \
--role-arn arn:aws:iam::<ACCOUNT_ID>:role/AgentCoreExecutionRole \
--region us-east-1- 创建 AWS CodePipeline：配置一条流水线，包含连接到你的 AWS CodeCommit 仓库的源、构建和部署阶段。
# Create the CodeCommit repository (if not already created)
aws codecommit create-repository \
--repository-name architecture-diagram-repo \
--repository-description "Source repo for architecture diagram pipeline"
# Create the CodePipeline (using a JSON input file)
aws codepipeline create-pipeline --cli-input-json file://pipeline-definition.json
# The pipeline-definition.json should define Source (CodeCommit),
# Build (CodeBuild), and Deploy (S3) stages. For the full JSON
# structure, see the AWS CodePipeline documentation.- 配置 Amazon S3 存储桶：为源代码暂存和文档托管创建存储桶，并设置适当的生命周期策略。
# Create the source code staging bucket
aws s3api create-bucket \
--bucket amzn-s3-demo-source-bucket1 \
--region us-east-1
# Create the documentation/diagrams hosting bucket
aws s3api create-bucket \
--bucket amzn-s3-demo-source-bucket2 \
--region us-east-1
# Enable versioning
aws s3api put-bucket-versioning \
--bucket amzn-s3-demo-source-bucket1 \
--versioning-configuration Status=Enabled
# Add lifecycle policy to expire old versions after 90 days
aws s3api put-bucket-lifecycle-configuration \
--bucket amzn-s3-demo-source-bucket1 \
--lifecycle-configuration '{
"Rules": [{\
"ID": "ExpireOldVersions",\
"Status": "Enabled",\
"NoncurrentVersionExpiration": {"NoncurrentDays": 90},\
"Filter": {"Prefix": ""}\
}]
}'- 创建 Amazon Bedrock Knowledge Bases：配置一个知识库，以 Amazon S3 架构图存储桶作为数据源（范围限定为 metadata/ 和 mermaid/ 前缀），以 Amazon Titan Text Embeddings v2 作为嵌入模型，以 Amazon S3 作为向量存储。设置分层分块，父块 1,500 个令牌（token），子块 300 个令牌。
# Create the Knowledge Base
aws bedrock-agent create-knowledge-base \
--name architecture-diagrams-kb \
--role-arn arn:aws:iam::<ACCOUNT_ID>:role/BedrockKnowledgeBaseRole \
--knowledge-base-configuration '{
"type": "VECTOR",
"vectorKnowledgeBaseConfiguration": {
"embeddingModelArn": "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0"
}
}' \
--storage-configuration '{
"type": "S3",
"s3Configuration": {
"bucketArn": "arn:aws:s3:::amzn-s3-demo-source-bucket1-<ACCOUNT_ID>"
}
}'
# Create the data source with hierarchical chunking
aws bedrock-agent create-data-source \
--knowledge-base-id <KNOWLEDGE_BASE_ID> \
--name diagrams-s3-source \
--data-source-configuration '{
"type": "S3",
"s3Configuration": {
"bucketArn": "arn:aws:s3:::amzn-s3-demo-source-bucket1-<ACCOUNT_ID>",
"inclusionPrefixes": ["metadata/", "mermaid/"]
}
}' \
--vector-ingestion-configuration '{
"chunkingConfiguration": {
"chunkingStrategy": "HIERARCHICAL",
"hierarchicalChunkingConfiguration": {
"levelConfigurations": [\
{"maxTokens": 1500},\
{"maxTokens": 300}\
],
"overlapTokens": 60
}
}
}'- 建立监控：为流水线失败和 AgentCore 调用错误配置 Amazon CloudWatch 告警。
# Create an SNS topic for alerts
aws sns create-topic --name pipeline-alerts
# Subscribe your email to the alerts topic
aws sns subscribe \
--topic-arn arn:aws:sns:us-east-1:<ACCOUNT_ID>:pipeline-alerts \
--protocol email \
--notification-endpoint your-team@example.com
# CloudWatch alarm for pipeline execution failures
aws cloudwatch put-metric-alarm \
--alarm-name pipeline-execution-failure \
--namespace AWS/CodePipeline \
--metric-name PipelineExecutionFailure \
--dimensions Name=PipelineName,Value=architecture-diagram-pipeline \
--statistic Sum --period 300 --threshold 1 \
--comparison-operator GreaterThanOrEqualToThreshold \
--evaluation-periods 1 \
--alarm-actions arn:aws:sns:us-east-1:<ACCOUNT_ID>:pipeline-alerts
# CloudWatch alarm for AgentCore invocation errors
aws cloudwatch put-metric-alarm \
--alarm-name agentcore-invocation-errors \
--namespace AWS/BedrockAgentCore \
--metric-name InvocationErrors \
--dimensions Name=AgentName,Value=architecture-diagram-agent \
--statistic Sum --period 300 --threshold 5 \
--comparison-operator GreaterThanOrEqualToThreshold \
--evaluation-periods 1 \
--alarm-actions arn:aws:sns:us-east-1:<ACCOUNT_ID>:pipeline-alerts- 测试流水线：触发一次手工执行，以验证端到端功能，包括知识库接入和查询结果，然后再启用自动触发。
# Trigger a manual pipeline execution
aws codepipeline start-pipeline-execution \
--name architecture-diagram-pipeline
# Check pipeline execution status
aws codepipeline get-pipeline-execution \
--pipeline-name architecture-diagram-pipeline \
--pipeline-execution-id <EXECUTION_ID>
# Trigger Knowledge Base ingestion
aws bedrock-agent start-ingestion-job \
--knowledge-base-id <KNOWLEDGE_BASE_ID> \
--data-source-id <DATA_SOURCE_ID>
# Check ingestion job status
aws bedrock-agent get-ingestion-job \
--knowledge-base-id <KNOWLEDGE_BASE_ID> \
--data-source-id <DATA_SOURCE_ID> \
--ingestion-job-id <INGESTION_JOB_ID>
# Test a query against the Knowledge Base
aws bedrock-agent-runtime retrieve \
--knowledge-base-id <KNOWLEDGE_BASE_ID> \
--retrieval-query '{"text": "What reconnection strategy does the system use?"}'- 清理：为避免持续产生费用，当你不再需要本演练创建的资源时，删除它们：
# Delete Codepipeline
aws codepipeline delete-pipeline --name architecture-diagram-pipeline
# Delete CodeBuild Project
aws codebuild delete-project --name architecture-diagram-build
# Delete the Amazon Bedrock knowledge base and data source:
aws bedrock-agent delete-data-source \
--knowledge-base-id <KNOWLEDGE_BASE_ID> \
--data-source-id <DATA_SOURCE_ID>
aws bedrock-agent delete-knowledge-base \
--knowledge-base-id <KNOWLEDGE_BASE_ID>
# Empty and delete the Amazon S3 buckets:
aws s3 rm s3://amzn-s3-demo-source-bucket1 --recursive
aws s3api delete-bucket --bucket amzn-s3-demo-source-bucket1
aws s3 rm s3://amzn-s3-demo-source-bucket2 --recursive
aws s3api delete-bucket --bucket amzn-s3-demo-source-bucket2
# Delete the AgentCore agent:
agentcore delete --agent-name architecture-diagram-agent --region us-east-1
# Delete the CloudWatch alarms and SNS topics:
aws cloudwatch delete-alarms \
--alarm-names pipeline-execution-failure agentcore-invocation-errors
aws sns delete-topic \
--topic-arn arn:aws:sns:us-east-1:<ACCOUNT_ID>:pipeline-alerts真实使用场景
Amazon Bedrock Knowledge Bases 加快开发者上手，支持安全的遗留系统现代化，支撑可审计的合规，并通过把静态图转变成可搜索的自然语言查询来提高可发现性。它还促进微服务上的跨团队协作，并通过生成的图可视化系统复杂性和依赖，帮助识别技术债。
对一家全球银行间经纪商，该方案按每周节奏，在 20 个仓库和服务上生成七种图类型，为其电子交易平台维护当前的架构文档。这支持合规审计、开发者上手，以及跨团队查看实时交易流的服务依赖。
收益
该方案自 2025 年 12 月起在一家大型金融服务公司的生产环境中运行。该公司是 AWS 的战略客户，业务跨越 20 个仓库，每周生成超过 140 张架构图，且没有手工开销。
基于连续六个月生产使用的内部测量，可衡量的业务影响相当显著。交付周期从 10 天压缩到 3 天。消息吞吐量翻倍，平均恢复时间减少 20%。生产事件减少 30%。审计准备和架构决策记录以前需要 2 周，现在 2 天完成。开发者上手从 4 周加速到 1 周。
以前每个仓库要花 2 到 4 小时的文档工作，现在需要 5 分钟。智能体方法相比单次 API 调用节省 40% 成本，而跨越 AgentCore、Amazon S3 和 Amazon Bedrock Knowledge Bases 的无服务器架构会在整个资产范围内自动扩展，无需管理基础设施。
这不是概念验证。它是一套大规模、多智能体的生产系统，解决一个真实且反复出现的客户问题：在企业规模上维护全面、可搜索且始终最新的架构文档。
后续步骤
要在你的组织中实施该方案：
- 先用 5–10 个仓库做试点项目，以验证该方法。
- 收集开发者和架构师对图质量、有用性以及知识库查询相关性的反馈。
- 扩展到更多仓库，并按你的具体需要定制图类型。
- 与现有文档系统集成，例如 Confluence 或内部维基，并把 Amazon Bedrock Knowledge Bases 连接到聊天界面或开发者门户，以便自助访问。
- 探索高级知识库功能，例如用于按仓库限定查询的元数据过滤，以及用于交互式架构探索的多轮对话支持。
结论
用 AgentCore 和 AWS CodePipeline 自动化架构文档，把一个手工、耗时的过程转变成顺畅、可扩展的工作流。智能体方法通过自我纠正提供可靠性，通过聚焦的模型交互提供成本效率，通过无服务器设计提供基础设施独立性。Amazon Bedrock Knowledge Bases 把这一价值延伸出去，使生成的文档可以通过自然语言立即被发现，从而让架构知识不仅是最新的，也能被每位利益相关者使用。
一家全球银行间经纪商今天就在生产中证明了这一点：在 20 个仓库上每周生成超过 140 张图，没有手工开销，把原先每周数小时的任务变成一个自动化、可查询的知识系统。采用该方案后，团队可以维护全面、最新且可搜索的架构文档，而没有传统开销，从而支持更快上手、合规就绪和更明智的架构决策。
PRIMARY_SOURCE: https://aws.amazon.com/blogs/machine-learning/from-code-to-diagrams-agentic-architecture-documentation-with-amazon-bedrock-agentcore
- #部署步骤
- #知识库
- #监控告警
- #清理回滚
- #CI/CD
