diff --git a/docker-compose.yml b/docker-compose.yaml similarity index 52% rename from docker-compose.yml rename to docker-compose.yaml index 6994dc7..43c84ad 100644 --- a/docker-compose.yml +++ b/docker-compose.yaml @@ -6,7 +6,7 @@ x-default: &default logging: driver: json-file options: - max-size: 1m + max-size: 100m services: app: @@ -16,8 +16,16 @@ services: dockerfile: Dockerfile args: - PORT=${PORT:-3001} - image: ${DOCKER_REGISTRY:-docker.io}/{SERVICE_NAME:-mcp-template-python}:${BUILD_VERSION:-latest} + image: ${DOCKER_REGISTRY:-docker.io}/${SERVICE_NAME:-mcp-template-python}:${BUILD_VERSION:-latest} ports: - - "${EXPOSE_PORT:-3001}:${PORT:-3001}" + - "${MCP_PORT_OVERRIDE:-3001}:${PORT:-3001}" env_file: - .env + deploy: + resources: + limits: + cpus: '0.50' + memory: 512M + reservations: + cpus: '0.25' + memory: 256M diff --git a/helm/mcp-template-python/README.md b/helm/mcp-template-python/README.md index bdca6aa..f0954c2 100644 --- a/helm/mcp-template-python/README.md +++ b/helm/mcp-template-python/README.md @@ -1,36 +1,36 @@ -# MCP Template Python - Helm Chart 配置说明 +# MCP Template Python - Helm Chart Configuration Guide -## 快速开始 +## Quick Start -### 1. 基础部署 +### 1. Basic Deployment ```bash -# 验证配置 +# Validate configuration make helm-lint -# 开发环境部署 +# Development environment deployment make helm-install -# 更新部署 +# Update deployment make helm-upgrade -# 卸载 +# Uninstall make helm-uninstall ``` -### 2. 生产环境部署 +### 2. Production Environment Deployment ```bash -# 首次部署 +# Initial deployment make helm-install-prod -# 更新部署 +# Update deployment make helm-upgrade-prod ``` -## 核心配置 +## Core Configuration -### 镜像配置 +### Image Configuration ```yaml image: @@ -39,7 +39,7 @@ image: pullPolicy: IfNotPresent ``` -### 服务配置 +### Service Configuration ```yaml service: @@ -48,7 +48,7 @@ service: targetPort: 3001 ``` -### 环境变量 +### Environment Variables ```yaml env: @@ -56,7 +56,7 @@ env: MCP_DEFAULT_PORT: "3001" ``` -### 健康检查 +### Health Checks ```yaml livenessProbe: @@ -72,9 +72,9 @@ readinessProbe: initialDelaySeconds: 5 ``` -## 生产环境配置要点 +## Production Environment Configuration -### 1. 资源配置(必须设置) +### 1. Resource Configuration (Required) ```yaml resources: @@ -86,7 +86,7 @@ resources: memory: 256Mi ``` -### 2. 镜像仓库 +### 2. Image Registry ```yaml image: @@ -94,7 +94,7 @@ image: tag: "v1.0.0" ``` -### 3. 自动扩展 +### 3. Auto Scaling ```yaml autoscaling: @@ -104,7 +104,7 @@ autoscaling: targetCPUUtilizationPercentage: 70 ``` -### 4. Ingress 配置 +### 4. Ingress Configuration ```yaml ingress: @@ -117,23 +117,23 @@ ingress: pathType: ImplementationSpecific ``` -## 配置文件管理 +## Configuration File Management -### ConfigMap 配置 +### ConfigMap Configuration ```yaml configMap: enabled: true data: app.conf: | - # 应用配置 + # Application configuration log_level=info debug=false ``` -### 挂载配置文件 +### Mounting Configuration Files -在 `values.yaml` 中添加: +Add to `values.yaml`: ```yaml volumeMounts: @@ -147,9 +147,9 @@ volumes: name: mcp-template-python-config ``` -## 安全配置 +## Security Configuration -应用运行在非 root 用户下: +Application runs as non-root user: ```yaml securityContext: @@ -160,73 +160,73 @@ securityContext: - ALL ``` -## 部署前检查清单 +## Pre-Deployment Checklist -### 开发环境 +### Development Environment -- [ ] 修改 `values.yaml` 中的镜像仓库 -- [ ] 确认端口配置 -- [ ] 设置环境变量 +- [ ] Update image repository in `values.yaml` +- [ ] Confirm port configuration +- [ ] Set environment variables -### 生产环境 +### Production Environment -- [ ] 更新 `values-production.yaml` 中的镜像标签 -- [ ] 设置资源限制和请求 -- [ ] 配置域名和 TLS -- [ ] 确认副本数量 -- [ ] 检查健康检查路径 +- [ ] Update image tag in `values-production.yaml` +- [ ] Set resource limits and requests +- [ ] Configure domain name and TLS +- [ ] Confirm replica count +- [ ] Check health check paths -## 常用命令 +## Common Commands ```bash -# 查看部署状态 +# Check deployment status kubectl get pods -l app.kubernetes.io/name=mcp-template-python -# 查看服务 +# Check service kubectl get svc mcp-template-python -# 查看日志 +# View logs kubectl logs -l app.kubernetes.io/name=mcp-template-python -# 进入容器 +# Enter container kubectl exec -it deployment/mcp-template-python -- /bin/bash -# 查看配置 +# View configuration helm get values mcp-template-python ``` -## 故障排除 +## Troubleshooting -### 常见问题 +### Common Issues -1. **Pod 启动失败** - - 检查镜像是否存在 - - 确认资源配置是否合理 - - 查看 Pod 事件:`kubectl describe pod ` +1. **Pod Startup Failure** + - Check if image exists + - Confirm resource configuration is reasonable + - View Pod events: `kubectl describe pod ` -2. **健康检查失败** - - 确认应用是否提供 `/health` 端点 - - 检查端口配置是否正确 - - 调整探针延迟时间 +2. **Health Check Failure** + - Confirm application provides `/health` endpoint + - Check port configuration is correct + - Adjust probe delay times -3. **服务无法访问** - - 确认 Service 配置 - - 检查网络策略 - - 验证 Ingress 配置 +3. **Service Inaccessible** + - Confirm Service configuration + - Check network policies + - Verify Ingress configuration -### 获取帮助 +### Getting Help ```bash -# 查看 Chart 信息 +# View Chart information helm show chart helm/mcp-template-python -# 查看所有配置选项 +# View all configuration options helm show values helm/mcp-template-python -# 验证模板渲染 +# Validate template rendering helm template mcp-template-python helm/mcp-template-python ``` --- -**注意**:生产环境部署前,请务必更新 `values-production.yaml` 中的资源配置和域名设置。 +**Note**: Before production deployment, make sure to update the resource configuration and domain settings in `values-production.yaml`. diff --git a/uv.lock b/uv.lock index d7d9f89..9dfd9a0 100644 --- a/uv.lock +++ b/uv.lock @@ -13,7 +13,7 @@ wheels = [ [[package]] name = "anyio" -version = "4.10.0" +version = "4.11.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "exceptiongroup", marker = "python_full_version < '3.11'" }, @@ -21,9 +21,9 @@ dependencies = [ { name = "sniffio" }, { name = "typing-extensions", marker = "python_full_version < '3.13'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/f1/b4/636b3b65173d3ce9a38ef5f0522789614e590dab6a8d505340a4efe4c567/anyio-4.10.0.tar.gz", hash = "sha256:3f3fae35c96039744587aa5b8371e7e8e603c0702999535961dd336026973ba6", size = 213252, upload-time = "2025-08-04T08:54:26.451Z" } +sdist = { url = "https://files.pythonhosted.org/packages/c6/78/7d432127c41b50bccba979505f272c16cbcadcc33645d5fa3a738110ae75/anyio-4.11.0.tar.gz", hash = "sha256:82a8d0b81e318cc5ce71a5f1f8b5c4e63619620b63141ef8c995fa0db95a57c4", size = 219094, upload-time = "2025-09-23T09:19:12.58Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/6f/12/e5e0282d673bb9746bacfb6e2dba8719989d3660cdb2ea79aee9a9651afb/anyio-4.10.0-py3-none-any.whl", hash = "sha256:60e474ac86736bbfd6f210f7a61218939c318f43f9972497381f1c5e930ed3d1", size = 107213, upload-time = "2025-08-04T08:54:24.882Z" }, + { url = "https://files.pythonhosted.org/packages/15/b3/9b1a8074496371342ec1e796a96f99c82c945a339cd81a8e73de28b4cf9e/anyio-4.11.0-py3-none-any.whl", hash = "sha256:0287e96f4d26d4149305414d4e3bc32f0dcd0862365a4bddea19d7a1ec38c4fc", size = 109097, upload-time = "2025-09-23T09:19:10.601Z" }, ] [[package]] @@ -538,16 +538,16 @@ wheels = [ [[package]] name = "pydantic-settings" -version = "2.10.1" +version = "2.11.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "pydantic" }, { name = "python-dotenv" }, { name = "typing-inspection" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/68/85/1ea668bbab3c50071ca613c6ab30047fb36ab0da1b92fa8f17bbc38fd36c/pydantic_settings-2.10.1.tar.gz", hash = "sha256:06f0062169818d0f5524420a360d632d5857b83cffd4d42fe29597807a1614ee", size = 172583, upload-time = "2025-06-24T13:26:46.841Z" } +sdist = { url = "https://files.pythonhosted.org/packages/20/c5/dbbc27b814c71676593d1c3f718e6cd7d4f00652cefa24b75f7aa3efb25e/pydantic_settings-2.11.0.tar.gz", hash = "sha256:d0e87a1c7d33593beb7194adb8470fc426e95ba02af83a0f23474a04c9a08180", size = 188394, upload-time = "2025-09-24T14:19:11.764Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/58/f0/427018098906416f580e3cf1366d3b1abfb408a0652e9f31600c24a1903c/pydantic_settings-2.10.1-py3-none-any.whl", hash = "sha256:a60952460b99cf661dc25c29c0ef171721f98bfcb52ef8d9ea4c943d7c8cc796", size = 45235, upload-time = "2025-06-24T13:26:45.485Z" }, + { url = "https://files.pythonhosted.org/packages/83/d6/887a1ff844e64aa823fb4905978d882a633cfe295c32eacad582b78a7d8b/pydantic_settings-2.11.0-py3-none-any.whl", hash = "sha256:fe2cea3413b9530d10f3a5875adffb17ada5c1e1bab0b2885546d7310415207c", size = 48608, upload-time = "2025-09-24T14:19:10.015Z" }, ] [[package]] @@ -997,7 +997,7 @@ wheels = [ [[package]] name = "typer" -version = "0.19.1" +version = "0.19.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "click" }, @@ -1005,9 +1005,9 @@ dependencies = [ { name = "shellingham" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/03/ea/9cc57c3c627fd7a6a0907ea371019fe74c3ec00e3cf209a6864140a602ad/typer-0.19.1.tar.gz", hash = "sha256:cb881433a4b15dacc875bb0583d1a61e78497806741f9aba792abcab390c03e6", size = 104802, upload-time = "2025-09-20T08:59:22.692Z" } +sdist = { url = "https://files.pythonhosted.org/packages/21/ca/950278884e2ca20547ff3eb109478c6baf6b8cf219318e6bc4f666fad8e8/typer-0.19.2.tar.gz", hash = "sha256:9ad824308ded0ad06cc716434705f691d4ee0bfd0fb081839d2e426860e7fdca", size = 104755, upload-time = "2025-09-23T09:47:48.256Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/1e/fa/6473c00b5eb26a2ba427813107699d3e6f4e1a4afad3f7494b17bdef3422/typer-0.19.1-py3-none-any.whl", hash = "sha256:914b2b39a1da4bafca5f30637ca26fa622a5bf9f515e5fdc772439f306d5682a", size = 46876, upload-time = "2025-09-20T08:59:21.153Z" }, + { url = "https://files.pythonhosted.org/packages/00/22/35617eee79080a5d071d0f14ad698d325ee6b3bf824fc0467c03b30e7fa8/typer-0.19.2-py3-none-any.whl", hash = "sha256:755e7e19670ffad8283db353267cb81ef252f595aa6834a0d1ca9312d9326cb9", size = 46748, upload-time = "2025-09-23T09:47:46.777Z" }, ] [[package]] @@ -1042,16 +1042,16 @@ wheels = [ [[package]] name = "uvicorn" -version = "0.36.0" +version = "0.37.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "click" }, { name = "h11" }, { name = "typing-extensions", marker = "python_full_version < '3.11'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/ef/5e/f0cd46063a02fd8515f0e880c37d2657845b7306c16ce6c4ffc44afd9036/uvicorn-0.36.0.tar.gz", hash = "sha256:527dc68d77819919d90a6b267be55f0e76704dca829d34aea9480be831a9b9d9", size = 80032, upload-time = "2025-09-20T01:07:14.418Z" } +sdist = { url = "https://files.pythonhosted.org/packages/71/57/1616c8274c3442d802621abf5deb230771c7a0fec9414cb6763900eb3868/uvicorn-0.37.0.tar.gz", hash = "sha256:4115c8add6d3fd536c8ee77f0e14a7fd2ebba939fed9b02583a97f80648f9e13", size = 80367, upload-time = "2025-09-23T13:33:47.486Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/96/06/5cc0542b47c0338c1cb676b348e24a1c29acabc81000bced518231dded6f/uvicorn-0.36.0-py3-none-any.whl", hash = "sha256:6bb4ba67f16024883af8adf13aba3a9919e415358604ce46780d3f9bdc36d731", size = 67675, upload-time = "2025-09-20T01:07:12.984Z" }, + { url = "https://files.pythonhosted.org/packages/85/cd/584a2ceb5532af99dd09e50919e3615ba99aa127e9850eafe5f31ddfdb9a/uvicorn-0.37.0-py3-none-any.whl", hash = "sha256:913b2b88672343739927ce381ff9e2ad62541f9f8289664fa1d1d3803fa2ce6c", size = 67976, upload-time = "2025-09-23T13:33:45.842Z" }, ] [package.optional-dependencies]