masoodafar-web
421 lines
12 KiB
Markdown
421 lines
12 KiB
Markdown
# راهنمای Package کردن Proto Projects برای Production
|
|
|
|
> تاریخ: December 6, 2025
|
|
> وضعیت: Production Deployment Guide
|
|
|
|
---
|
|
|
|
## 🎯 مسئله
|
|
|
|
**Development (Local)**:
|
|
- استفاده از `<ProjectReference>` برای توسعه سریع
|
|
- تغییرات proto بلافاصله در همه پروژهها اعمال میشود
|
|
|
|
**Production (Server)**:
|
|
- استفاده از `<PackageReference>` و NuGet packages
|
|
- هر لایه پکیج خودش را منتشر میکند
|
|
- پروژههای بالاتر از NuGet server پکیجها را میگیرند
|
|
|
|
---
|
|
|
|
## 📦 معماری Packaging
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ LAYER 1: CMS Proto │
|
|
│ CMSMicroservice.Protobuf → Foursat.CMSMicroservice.Protobuf │
|
|
└────────────────────┬────────────────────────────────────────┘
|
|
│ (NuGet Package v1.0.x)
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ LAYER 2: BFF Proto (depends on CMS) │
|
|
│ BackOffice.BFF.*.Protobuf → Foursat.BackOffice.BFF.*.Protobuf │
|
|
│ FrontOffice.BFF.*.Protobuf → Foursat.FrontOffice.BFF.*.Protobuf │
|
|
└────────────────────┬────────────────────────────────────────┘
|
|
│ (NuGet Package v1.0.x)
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ LAYER 3: UI Apps (depends on BFF) │
|
|
│ BackOffice UI → uses Foursat.BackOffice.BFF.*.Protobuf │
|
|
│ FrontOffice UI → uses Foursat.FrontOffice.BFF.*.Protobuf │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Setup 1: Private NuGet Server
|
|
|
|
### گزینه A: BaGet (پیشنهادی - رایگان و ساده)
|
|
|
|
```bash
|
|
# نصب با Docker
|
|
docker run -d \
|
|
--name foursat-nuget \
|
|
--restart unless-stopped \
|
|
-p 5555:80 \
|
|
-e ApiKey=FOURSAT-SECRET-API-KEY-2025 \
|
|
-e Storage__Type=FileSystem \
|
|
-e Storage__Path=/var/baget/packages \
|
|
-e Database__Type=Sqlite \
|
|
-e Database__ConnectionString="Data Source=/var/baget/baget.db" \
|
|
-e Search__Type=Database \
|
|
-v /opt/foursat-nuget/packages:/var/baget/packages \
|
|
-v /opt/foursat-nuget/database:/var/baget \
|
|
loicsharma/baget:latest
|
|
|
|
# سرور روی http://YOUR_SERVER:5555 در دسترس خواهد بود
|
|
```
|
|
|
|
### گزینه B: Azure Artifacts
|
|
|
|
```bash
|
|
# اضافه کردن feed
|
|
az artifacts universal publish \
|
|
--organization https://dev.azure.com/yourorg \
|
|
--feed foursat-packages \
|
|
--name CMSMicroservice.Protobuf \
|
|
--version 1.0.0 \
|
|
--path ./nupkg
|
|
```
|
|
|
|
### گزینه C: GitHub Packages
|
|
|
|
```bash
|
|
# تنظیم authentication
|
|
dotnet nuget add source https://nuget.pkg.github.com/YOURORG/index.json \
|
|
--name github \
|
|
--username YOURNAME \
|
|
--password ghp_YOUR_TOKEN \
|
|
--store-password-in-clear-text
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Setup 2: تنظیمات Proto Projects
|
|
|
|
### 1. CMS Protobuf (لایه اول - پایه)
|
|
|
|
**CMSMicroservice.Protobuf.csproj** از قبل آماده است:
|
|
|
|
```xml
|
|
<PropertyGroup>
|
|
<TargetFramework>net9.0</TargetFramework>
|
|
<Version>1.0.0</Version>
|
|
<PackageId>Foursat.CMSMicroservice.Protobuf</PackageId>
|
|
<GeneratePackageOnBuild>false</GeneratePackageOnBuild>
|
|
|
|
<!-- اطلاعات پکیج -->
|
|
<Authors>FourSat Development Team</Authors>
|
|
<Company>FourSat</Company>
|
|
<Description>gRPC Protobuf contracts for CMS Microservice</Description>
|
|
<PackageTags>grpc;protobuf;foursat;cms</PackageTags>
|
|
<RepositoryUrl>https://github.com/foursat/cms</RepositoryUrl>
|
|
<PackageLicenseExpression>MIT</PackageLicenseExpression>
|
|
</PropertyGroup>
|
|
```
|
|
|
|
### 2. BackOffice.BFF Proto Projects (لایه دوم)
|
|
|
|
مثال برای **BackOffice.BFF.Products.Protobuf**:
|
|
|
|
```xml
|
|
<PropertyGroup>
|
|
<TargetFramework>net9.0</TargetFramework>
|
|
<Version>1.0.0</Version>
|
|
<PackageId>Foursat.BackOffice.BFF.Products.Protobuf</PackageId>
|
|
<GeneratePackageOnBuild>false</GeneratePackageOnBuild>
|
|
<Authors>FourSat Development Team</Authors>
|
|
<Company>FourSat</Company>
|
|
<Description>gRPC Protobuf contracts for BackOffice BFF - Products Module</Description>
|
|
<PackageTags>grpc;protobuf;foursat;backoffice</PackageTags>
|
|
</PropertyGroup>
|
|
|
|
<!-- Development: ProjectReference -->
|
|
<ItemGroup Condition="'$(Configuration)' == 'Debug'">
|
|
<ProjectReference Include="..\..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
|
|
</ItemGroup>
|
|
|
|
<!-- Production: PackageReference -->
|
|
<ItemGroup Condition="'$(Configuration)' == 'Release'">
|
|
<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="1.0.0" />
|
|
</ItemGroup>
|
|
```
|
|
|
|
### 3. FrontOffice.BFF Proto Projects (لایه دوم)
|
|
|
|
مشابه BackOffice.BFF:
|
|
|
|
```xml
|
|
<PropertyGroup>
|
|
<PackageId>Foursat.FrontOffice.BFF.Products.Protobuf</PackageId>
|
|
<Version>1.0.0</Version>
|
|
</PropertyGroup>
|
|
|
|
<ItemGroup Condition="'$(Configuration)' == 'Debug'">
|
|
<ProjectReference Include="..\..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
|
|
</ItemGroup>
|
|
|
|
<ItemGroup Condition="'$(Configuration)' == 'Release'">
|
|
<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="1.0.0" />
|
|
</ItemGroup>
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 فرآیند Deployment
|
|
|
|
### مرحله 1: Package CMS Protobuf
|
|
|
|
```bash
|
|
cd /home/masoud/Apps/project/FourSat/CMS/src/CMSMicroservice.Protobuf
|
|
|
|
# Build در حالت Release
|
|
dotnet build -c Release
|
|
|
|
# ایجاد NuGet package
|
|
dotnet pack -c Release -o ./nupkg
|
|
|
|
# Push به NuGet server
|
|
dotnet nuget push ./nupkg/Foursat.CMSMicroservice.Protobuf.1.0.0.nupkg \
|
|
--source http://YOUR_SERVER:5555/v3/index.json \
|
|
--api-key FOURSAT-SECRET-API-KEY-2025
|
|
```
|
|
|
|
### مرحله 2: Package BackOffice.BFF Protos
|
|
|
|
```bash
|
|
# تمام Proto projects را pack کن
|
|
cd /home/masoud/Apps/project/FourSat/BackOffice.BFF/src/Protobufs
|
|
|
|
for dir in */; do
|
|
if [ -f "$dir/*.csproj" ]; then
|
|
cd "$dir"
|
|
dotnet pack -c Release -o ../../nupkg
|
|
cd ..
|
|
fi
|
|
done
|
|
|
|
# Push همه packages
|
|
cd ../../nupkg
|
|
dotnet nuget push "Foursat.BackOffice.BFF.*.nupkg" \
|
|
--source http://YOUR_SERVER:5555/v3/index.json \
|
|
--api-key FOURSAT-SECRET-API-KEY-2025
|
|
```
|
|
|
|
### مرحله 3: Package FrontOffice.BFF Protos
|
|
|
|
```bash
|
|
cd /home/masoud/Apps/project/FourSat/FrontOffice.BFF/src/Protobufs
|
|
|
|
for dir in */; do
|
|
cd "$dir"
|
|
dotnet pack -c Release -o ../../nupkg
|
|
cd ..
|
|
done
|
|
|
|
cd ../../nupkg
|
|
dotnet nuget push "Foursat.FrontOffice.BFF.*.nupkg" \
|
|
--source http://YOUR_SERVER:5555/v3/index.json \
|
|
--api-key FOURSAT-SECRET-API-KEY-2025
|
|
```
|
|
|
|
### مرحله 4: تنظیم UI Projects برای Production
|
|
|
|
**BackOffice.csproj**:
|
|
|
|
```xml
|
|
<!-- Development -->
|
|
<ItemGroup Condition="'$(Configuration)' == 'Debug'">
|
|
<ProjectReference Include="..\..\BackOffice.BFF\src\Protobufs\BackOffice.BFF.Products.Protobuf\BackOffice.BFF.Products.Protobuf.csproj" />
|
|
<ProjectReference Include="..\..\BackOffice.BFF\src\Protobufs\BackOffice.BFF.User.Protobuf\BackOffice.BFF.User.Protobuf.csproj" />
|
|
<!-- ... سایر proto references -->
|
|
</ItemGroup>
|
|
|
|
<!-- Production -->
|
|
<ItemGroup Condition="'$(Configuration)' == 'Release'">
|
|
<PackageReference Include="Foursat.BackOffice.BFF.Products.Protobuf" Version="1.0.0" />
|
|
<PackageReference Include="Foursat.BackOffice.BFF.User.Protobuf" Version="1.0.0" />
|
|
<!-- ... سایر package references -->
|
|
</ItemGroup>
|
|
```
|
|
|
|
**FrontOffice.csproj**: مشابه
|
|
|
|
---
|
|
|
|
## 🔄 Versioning Strategy
|
|
|
|
### Semantic Versioning
|
|
|
|
```
|
|
MAJOR.MINOR.PATCH
|
|
|
|
1.0.0 → Initial release
|
|
1.0.1 → Bug fix (backward compatible)
|
|
1.1.0 → New feature (backward compatible)
|
|
2.0.0 → Breaking change
|
|
```
|
|
|
|
### مثال:
|
|
|
|
```xml
|
|
<!-- CMS Proto v1.0.0 -->
|
|
<Version>1.0.0</Version>
|
|
|
|
<!-- بعد از اضافه کردن فیلد جدید (backward compatible) -->
|
|
<Version>1.1.0</Version>
|
|
|
|
<!-- بعد از تغییر RPC signature (breaking) -->
|
|
<Version>2.0.0</Version>
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ Scripts خودکار
|
|
|
|
### pack-all-protos.sh
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
|
|
# رنگها برای output
|
|
GREEN='\033[0;32m'
|
|
BLUE='\033[0;34m'
|
|
RED='\033[0;31m'
|
|
NC='\033[0m' # No Color
|
|
|
|
NUGET_SERVER="http://YOUR_SERVER:5555/v3/index.json"
|
|
API_KEY="FOURSAT-SECRET-API-KEY-2025"
|
|
|
|
echo -e "${BLUE}🚀 Starting Proto Packaging Process...${NC}\n"
|
|
|
|
# 1. CMS Protobuf
|
|
echo -e "${GREEN}📦 Step 1: Packaging CMS Protobuf${NC}"
|
|
cd /home/masoud/Apps/project/FourSat/CMS/src/CMSMicroservice.Protobuf
|
|
dotnet pack -c Release -o ./nupkg
|
|
dotnet nuget push ./nupkg/*.nupkg --source $NUGET_SERVER --api-key $API_KEY --skip-duplicate
|
|
|
|
# 2. BackOffice.BFF Protos
|
|
echo -e "${GREEN}📦 Step 2: Packaging BackOffice.BFF Protos${NC}"
|
|
cd /home/masoud/Apps/project/FourSat/BackOffice.BFF/src/Protobufs
|
|
for dir in BackOffice.BFF.*.Protobuf/; do
|
|
if [ -d "$dir" ]; then
|
|
echo " → Packaging $dir"
|
|
cd "$dir"
|
|
dotnet pack -c Release -o ../../../nupkg
|
|
cd ..
|
|
fi
|
|
done
|
|
cd ../../nupkg
|
|
dotnet nuget push Foursat.BackOffice.BFF.*.nupkg --source $NUGET_SERVER --api-key $API_KEY --skip-duplicate
|
|
|
|
# 3. FrontOffice.BFF Protos
|
|
echo -e "${GREEN}📦 Step 3: Packaging FrontOffice.BFF Protos${NC}"
|
|
cd /home/masoud/Apps/project/FourSat/FrontOffice.BFF/src/Protobufs
|
|
for dir in FrontOffice.BFF.*.Protobuf/; do
|
|
if [ -d "$dir" ]; then
|
|
echo " → Packaging $dir"
|
|
cd "$dir"
|
|
dotnet pack -c Release -o ../../../nupkg
|
|
cd ..
|
|
fi
|
|
done
|
|
cd ../../nupkg
|
|
dotnet nuget push Foursat.FrontOffice.BFF.*.nupkg --source $NUGET_SERVER --api-key $API_KEY --skip-duplicate
|
|
|
|
echo -e "\n${GREEN}✅ All packages published successfully!${NC}"
|
|
```
|
|
|
|
اجرا:
|
|
```bash
|
|
chmod +x pack-all-protos.sh
|
|
./pack-all-protos.sh
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 NuGet.Config برای Development
|
|
|
|
**nuget.config** در root:
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<configuration>
|
|
<packageSources>
|
|
<!-- Official NuGet -->
|
|
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
|
|
|
|
<!-- FourSat Private NuGet Server -->
|
|
<add key="foursat" value="http://YOUR_SERVER:5555/v3/index.json" />
|
|
</packageSources>
|
|
|
|
<packageSourceCredentials>
|
|
<foursat>
|
|
<add key="Username" value="foursat" />
|
|
<add key="ClearTextPassword" value="FOURSAT-SECRET-API-KEY-2025" />
|
|
</foursat>
|
|
</packageSourceCredentials>
|
|
</configuration>
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 بررسی Packages
|
|
|
|
```bash
|
|
# لیست packages روی server
|
|
curl http://YOUR_SERVER:5555/v3/search?q=foursat
|
|
|
|
# دانلود package
|
|
dotnet add package Foursat.CMSMicroservice.Protobuf --version 1.0.0
|
|
|
|
# بررسی dependency tree
|
|
dotnet list package --include-transitive
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 خلاصه Packages
|
|
|
|
| Package | Layer | Depends On | Version |
|
|
|---------|-------|------------|---------|
|
|
| Foursat.CMSMicroservice.Protobuf | 1 | - | 1.0.x |
|
|
| Foursat.BackOffice.BFF.Products.Protobuf | 2 | CMS Proto | 1.0.x |
|
|
| Foursat.BackOffice.BFF.User.Protobuf | 2 | CMS Proto | 1.0.x |
|
|
| Foursat.BackOffice.BFF.*.Protobuf (14 pkg) | 2 | CMS Proto | 1.0.x |
|
|
| Foursat.FrontOffice.BFF.Products.Protobuf | 2 | CMS Proto | 1.0.x |
|
|
| Foursat.FrontOffice.BFF.*.Protobuf (8 pkg) | 2 | CMS Proto | 1.0.x |
|
|
|
|
**جمع**: ~23 NuGet packages
|
|
|
|
---
|
|
|
|
## 🎯 مزایا
|
|
|
|
✅ **Development**: سریع (ProjectReference)
|
|
✅ **Production**: مستقل (PackageReference)
|
|
✅ **Versioning**: کنترل دقیق تغییرات
|
|
✅ **CI/CD**: خودکارسازی آسان
|
|
✅ **Rollback**: برگشت به نسخه قبلی ساده
|
|
✅ **Team Work**: همکاری بهتر روی Proto ها
|
|
|
|
---
|
|
|
|
## 🚨 نکات مهم
|
|
|
|
1. **همیشه از Semantic Versioning استفاده کنید**
|
|
2. **Breaking changes** = Major version bump (2.0.0)
|
|
3. **Proto changes باید documented باشند**
|
|
4. **هر push به production نیاز به package جدید دارد**
|
|
5. **Development با Debug build** = ProjectReference
|
|
6. **Production با Release build** = PackageReference
|
|
|
|
---
|
|
|
|
## 📞 Support
|
|
|
|
سوال یا مشکل؟
|
|
- داکیومنت: `/home/masoud/Apps/project/FourSat/PROTO-PACKAGING-GUIDE.md`
|
|
- BaGet UI: http://YOUR_SERVER:5555
|
|
- Team: FourSat Development Team
|