admin/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8f02cec22f84e164d70e3ae43422af42229ba088
docs/archive/collected-docs/root/PROTO-PACKAGING-GUIDE.md
T
masoodafar-web 5965b98728 update
2026-01-03 18:27:49 +03:30

12 KiB
Raw Blame History

راهنمای 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 (پیشنهادی - رایگان و ساده)

# نصب با 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

# اضافه کردن 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

# تنظیم 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 از قبل آماده است:

<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:

<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:

<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

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

# تمام 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

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:

<!-- 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

مثال:

<!-- 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

#!/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}"

اجرا:

chmod +x pack-all-protos.sh
./pack-all-protos.sh

📋 NuGet.Config برای Development

nuget.config در root:

<?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

# لیست 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
Reference in New Issue View Git Blame Copy Permalink