在將本地資料同步到 Azure SQL Database 的專案中，我遇到了兩個問題：

1. 安全性：連線字串裡不想寫死帳號密碼
2. 效能：用 pyodbc 逐筆 UPDATE 速度慢到不行

這篇文章紀錄我怎麼用 Azure Managed Identity + Access Token 取代密碼驗證，並透過 fast_executemany 大幅提升批次寫入效能。同時也整理了幾個常見疑問：有沒有 Token 差在哪、ActiveDirectoryMsi 與手動 Token 有何不同、兩者效能是否有差。

環境

• Python 3.11+
• pyodbc + ODBC Driver 18 for SQL Server
• azure-identity
• Azure SQL Database（已啟用 Entra ID / Managed Identity）

pip install pyodbc azure-identity

問題一：不想在程式裡放密碼

有無 Access Token 的差別

傳統帳密驗證的連線字串長這樣：

# 傳統帳密驗證
conn_str = (
    "Driver={ODBC Driver 18 for SQL Server};"
    "Server=your-server.database.windows.net;"
    "Database=your-db;"
    "UID=myuser;"
    "PWD=mypassword;"
)
conn = pyodbc.connect(conn_str)

Access Token 驗證則是拿掉帳密，改用 attrs_before 注入 Token：

# Access Token 驗證
conn_str = (
    "Driver={ODBC Driver 18 for SQL Server};"
    "Server=your-server.database.windows.net;"
    "Database=your-db;"
    "Encrypt=yes;"
    # 沒有 UID / PWD
)
conn = pyodbc.connect(conn_str, attrs_before={1256: token_struct})

兩者的核心差異：

一句話總結：帳密是「你知道什麼」，Token 是「你是誰（身份）」，在雲端環境推薦用 Token，省去密碼管理的麻煩。

解法：用 Azure Identity 取得 Access Token

azure-identity 套件提供的 DefaultAzureCredential 可以依序嘗試多種驗證方式（環境變數、Managed Identity、Azure CLI 登入等），在本機開發和正式環境都能無縫切換。

import struct
import pyodbc
from azure.identity import DefaultAzureCredential

# 在程式啟動時初始化一次，讓 Token 可以被快取重複使用
azure_credential = DefaultAzureCredential()

def get_mssql_connection(server, database, driver):
    # 每次建立連線時呼叫 get_token()，有快取就回快取，快到期會自動刷新
    token_object = azure_credential.get_token("https://database.windows.net/.default")

    # pyodbc 要求 Token 必須以特定格式打包
    token_bytes = token_object.token.encode("utf-16-le")
    token_struct = struct.pack(f"<I{len(token_bytes)}s", len(token_bytes), token_bytes)

    # 連線字串不帶 UID/PWD，改用 attrs_before 注入 Token
    # SQL_COPT_SS_ACCESS_TOKEN = 1256
    conn_str = f"Driver={driver};Server={server};Database={database};Encrypt=yes;TrustServerCertificate=no;"
    conn = pyodbc.connect(conn_str, attrs_before={1256: token_struct})
    return conn

關鍵細節：

• Token 必須先用 utf-16-le 編碼，再用 struct.pack 包成 <I{n}s 格式
• attrs_before={1256: token_struct} 是 pyodbc 注入 SQL_COPT_SS_ACCESS_TOKEN 的方式
• 連線字串裡不能加 Authentication=...，否則會與 Token 驗證衝突

補充：Authentication=ActiveDirectoryMsi vs 手動 Access Token

Azure SQL 還有另一種無密碼寫法：在連線字串直接加 Authentication=ActiveDirectoryMsi，讓 ODBC Driver 自己去拿 Token：

# ActiveDirectoryMsi 寫法：Driver 自己處理 Token
conn_str = (
    "Driver={ODBC Driver 18 for SQL Server};"
    "Server=your-server.database.windows.net;"
    "Database=your-db;"
    "Authentication=ActiveDirectoryMsi;"
    "Encrypt=yes;"
)
conn = pyodbc.connect(conn_str)

兩種方式的比較：

	ActiveDirectoryMsi	手動 Access Token
程式碼複雜度	簡單，Driver 全包	需要自己打包 struct
套件依賴	只需 pyodbc	需要 azure-identity
Token 快取	Driver 自己管，不透明	自己控制（全域 credential 物件）
彈性	僅限 MSI	可用任何 Credential（CLI、SP、環境變數…）
本機開發	只能在 Azure 環境跑	az login 本機也能用
User-Assigned MSI	需加 UID=client-id	ManagedIdentityCredential(client_id=...)

效能有差嗎？

連線建立後的 SQL 執行效能：完全一樣。 差別只在取 Token 的開銷，且僅影響建立連線那一刻：

該選哪個？

實務上幾乎不用思考，直接選手動管理就對了——只要記住一個原則：

每次 connect() 都重新呼叫 get_token()，不要把打包好的 token_struct 存起來重複用。

# ❌ 危險：token_struct 是靜態 bytes，1 小時後 Token 過期，重連時會爆
token_struct = pack_token(azure_credential.get_token(...))
# ... 之後某處重新 connect() 但沿用舊的 token_struct

# ✅ 正確：每次建立連線時才呼叫 get_token()
def get_conn():
    token = azure_credential.get_token(...)  # 有快取就回快取，快到期自動刷新
    return pyodbc.connect(conn_str, attrs_before={1256: pack_token(token)})

azure-identity 的 get_token() 本身有快取，不用擔心每次都打網路，讓它去判斷就好。

問題二：逐筆 UPDATE 太慢

初版程式是這樣跑的：

for row in rows:
    cursor.execute("UPDATE users SET name = ?, email = ? WHERE account = ?", row)
conn.commit()

幾百筆資料就要花好幾秒，每一筆都是一次來回的 network round-trip。

解法：executemany + fast_executemany = True

cursor = conn.cursor()

# 啟用 fast_executemany：改用 ODBC 的批次參數傳輸，大幅減少 round-trip
cursor.fast_executemany = True

sql = "UPDATE users SET name = ?, email = ? WHERE account = ?"
cursor.executemany(sql, rows)  # rows 是 list of tuples

conn.commit()

fast_executemany 是 pyodbc 的一個優化開關，啟用後會將所有參數打包成一個批次送出，而不是一筆一筆傳送，對幾百到幾千筆的批次操作效果非常明顯。

完整範例

import sqlite3
import pyodbc
import os
import struct
from azure.identity import DefaultAzureCredential

SERVER   = "your-server.database.windows.net"
DATABASE = "your-database"
DRIVER   = "{ODBC Driver 18 for SQL Server}"

# 全域初始化一次，Token 快取由 azure-identity 管理
azure_credential = DefaultAzureCredential()


def get_mssql_connection():
    # 每次連線都呼叫 get_token()，讓 azure-identity 決定要不要刷新
    token_object = azure_credential.get_token("https://database.windows.net/.default")
    token_bytes  = token_object.token.encode("utf-16-le")
    token_struct = struct.pack(f"<I{len(token_bytes)}s", len(token_bytes), token_bytes)
    conn_str = (
        f"Driver={DRIVER};Server={SERVER};Database={DATABASE};"
        "Encrypt=yes;TrustServerCertificate=no;"
    )
    return pyodbc.connect(conn_str, attrs_before={1256: token_struct})


def sync_sqlite_to_mssql(sqlite_path: str):
    if not os.path.exists(sqlite_path):
        print(f"SQLite not found: {sqlite_path}")
        return

    with sqlite3.connect(sqlite_path) as sqlite_conn:
        rows = sqlite_conn.execute(
            "SELECT name, email, account FROM employee WHERE status = 'active'"
        ).fetchall()

    if not rows:
        print("No rows to sync.")
        return

    print(f"Syncing {len(rows)} rows...")

    with get_mssql_connection() as mssql_conn:
        cursor = mssql_conn.cursor()
        cursor.fast_executemany = True
        cursor.executemany(
            "UPDATE users SET name = ?, email = ? WHERE account = ?",
            rows,
        )
        mssql_conn.commit()

    print("Done.")


if __name__ == "__main__":
    sync_sqlite_to_mssql("portal.db")

前置設定：讓 Managed Identity 能存取 Azure SQL

在 Azure SQL 裡執行以下 T-SQL，把你的 Managed Identity 或 Entra ID 帳號加入：

-- 使用 Azure AD 帳號登入後執行
CREATE USER [your-managed-identity-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [your-managed-identity-name];
ALTER ROLE db_datawriter ADD MEMBER [your-managed-identity-name];

本機開發時，用 Azure CLI 登入後 DefaultAzureCredential 就會自動使用你的帳號：

az login

小結

兩個改動加起來不超過 10 行，卻同時解決了安全性與效能問題，值得加進你的 Azure SQL 工具箱。

要實現這個功能，你需要完成三個步驟：啟用身份識別、資料庫授權、以及修改 Python 連線字串。

第一步：在 Azure 資源上啟用受控識別

在你運行 Python 程式碼的資源（例如 Azure VM, App Service 或 Function）的頁面：

1. 點選左側選單的 「身分識別」(Identity)。
2. 在 「系統指派」 頁籤下，將狀態改為 「開啟」 並儲存。
3. 系統會產生一個 物件識別碼 (Object ID)，請記住這個資源的名稱。

上面的截圖來看，你目前是在 「Azure SQL Database」 的介面裡。

受控識別（Managed Identity）不是在資料庫（Database）上開啟的，而是在「跑 Python 程式碼的那個東西」上面開啟的。

請想像：

• SQL Database 是「銀行」。
• 你的 Python 程式碼（跑在 VM、App Service 或 Function 上）是「進去辦事的人」。

你現在需要在「辦事的人」身上發一張身分證（啟用受控識別），然後再去「銀行」告訴櫃檯（資料庫）說：「看到拿這張身分證的人就讓他進來」。

接下來你該怎麼做：

1. 找到「發身分證」的地方

請在 Azure Portal 最上方的搜尋框，搜尋你跑 Python 程式碼的資源名稱。

• 如果你是在 Azure VM 跑：去該 VM 的頁面，找左側選單的「身分識別」。
• 如果你是在 App Service 跑：去該 App Service 的頁面，找左側選單的「身分識別」。
• 如果你是在 Azure Function 跑：去該 Function 的頁面，找左側選單的「身分識別」。

進入後，你就會看到我上一個回覆說的「系統指派」狀態，將它改為 「開啟」。

2. 在資料庫（也就是你截圖的這個地方）授權

當你在上面的資源開啟受控識別後，回到你截圖的這個 SQL Database 介面：

1. 點擊左側選單的 「查詢編輯器 (預覽)」(Query editor)。
2. 用你的管理員帳號登入。
3. 執行以下指令（假設你的 VM 或 App Service 名字叫 my-python-app）：

SQL

CREATE USER [my-python-app] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [my-python-app];
ALTER ROLE db_datawriter ADD MEMBER [my-python-app];

補充：截圖中的發現

從你的截圖中可以看到，在 「安全性」 區塊下，有一行：

• 系統指派的身分識別：已啟用

這指的是 「SQL Server 自己」 的身分，通常是用來讓 SQL 去讀取 Key Vault 等其他資源用的。這不是給你的 Python 程式連線用的。 總結： 請去尋找你運行 Python 的那個 Azure 資源（VM / App Service），在那裡開啟身分識別。

了解更多: 利用客戶自控金鑰支援透明資料加密的受控識別
https://learn.microsoft.com/zh-tw/azure/azure-sql/database/transparent-data-encryption-byok-identity?view=azuresql&WT.mc_id=Portal-SqlAzureExtension

▋ 數據安全的大門與那把遺失的鑰匙

在數位世界裡，我們使用「透明資料加密」技術，這就像是在資料庫門口裝了一道自動感應門，資料進出時會自動上鎖或解鎖。傳統做法是讓雲端平台幫你管理這把鑰匙，這對大多數人來說很方便。然而，對於需要極高掌控權的管理者來說，這就像是把身家財產的進出權限完全交給外人，一旦發生資安爭議，你可能無法第一時間主動切換鎖頭。

▋ 拿回屬於你的主權鑰匙

為了解決這個信任缺口，現在有一種「客戶管理金鑰」的機制。簡單來說，這就是讓你自備鎖頭與鑰匙。當你的資料庫要啟動加密功能時，系統不再使用預設的鑰匙，而是去你的私密保險庫中讀取你指定的「身份證明」。這確保了只有經過你授權的特定身份，才能啟動那把開啟資料的鑰匙。

▋ 建立你的專屬數位防線

如果你希望全面掌控數據的安全命運，可以嘗試以下步驟：

• 在雲端環境中建立一個專屬的「身份識別」，這就像是為你的資料庫申請一張專屬的身分證。
• 設定嚴格的存取權限，確保只有這個「身份」能接觸到你的加密鑰匙。
• 定期檢查這把鑰匙的使用紀錄，確保沒有任何未經授權的嘗試。

第二步：在 SQL Database 中授權

SQL Server 預設不認識這個受控識別，你必須進到資料庫裡幫它「開門」：

1. 使用 Active Directory 管理員 帳號登入 SQL Database（可用 Azure Portal 的 Query Editor）。
2. 執行以下 SQL 指令（將 <identity-name> 替換為你的 Azure 資源名稱）：

SQL

-- 建立資料庫使用者
CREATE USER [<identity-name>] FROM EXTERNAL PROVIDER;

-- 授予讀取/寫入權限 (視需求調整角色)
ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];

如果你是在 Azure App Service 或 Azure VM 上啟用的受控識別，該「顯示名稱」通常就是你的 資源名稱。

• 錯誤做法：CREATE USER [1234-1234-1234-1234-1234] ... (不可使用 ID)
• 正確做法：CREATE USER [你的AppService名稱] FROM EXTERNAL PROVIDER;

如果你不確定名稱，或者名稱有特殊字元，你可以直接使用 SID (這對應到你看到的物件識別碼) 來建立，這樣最準確：

-- 請將 '1234-1234-1234-1234-1234' 替換為你在身分識別頁面看到的 Object ID
CREATE USER [MyManagedIdentityName] 
WITH OBJECT_ID = '1234-1234-1234-1234-1234';

-- 接著再授權
ALTER ROLE db_datareader ADD MEMBER [MyManagedIdentityName];

第三步：修改 Python 連線字串

使用受控識別時，連線字串不需要 UID 和 PWD，而是改用 Authentication=ActiveDirectoryMsi。

Python

import pyodbc

# 設定基礎參數
server = 'your-server.database.windows.net'
database = 'your-database'
driver = '{ODBC Driver 18 for SQL Server}'

# 系統指派受控識別的連線字串
connection_string = (
    f"Driver={driver};"
    f"Server={server};"
    f"Database={database};"
    "Authentication=ActiveDirectoryMsi;"  # 關鍵設定
    "Encrypt=yes;"
    "TrustServerCertificate=no;"
    "Connection Timeout=30;"
)

def connect_and_query():
    try:
        print(f"Connecting to {server} using Managed Identity...")
        conn = pyodbc.connect(connection_string)
        print("連線成功！")
        return conn
    except Exception as e:
        print(f"連線失敗: {e}")

# 執行連線
conn = connect_and_query()

關鍵筆記：

• 環境限制：Authentication=ActiveDirectoryMsi 只能在 Azure 環境內 運行（例如在 Azure VM 上跑）。如果你在自己的電腦（在地端）跑這段程式碼會報錯，因為地端環境沒有 Managed Identity 憑證。
• 驅動程式：請確保你的環境中安裝了 ODBC Driver 17 或 18，舊版驅動程式可能不支援 ActiveDirectoryMsi 參數。
• 優點：即使你更換了密碼，或者這台機器被刪除了，都不需要去改程式碼，這就是「無密碼連線」的強大之處。

執行以下 SQL 指令時遇到 Error:

A connection was successfully established with the server, but then an error occurred during the pre-login handshake. (provider: TCP Provider, error: 0 – An existing connection was forcibly closed by the remote host.)

Failed to execute the query

這個錯誤「An existing connection was forcibly closed by the remote host」發生在 Pre-login handshake (預先登錄握手) 階段，通常不是程式碼邏輯問題，而是 網路層 或 防火牆 的攔截。

這代表你的 Python 程式已經碰到了 SQL Server 的大門，但 SQL Server 因為某些安全規則直接把連線「踢掉」了。

請檢查以下三個最常見的原因：

1. Azure SQL 防火牆未允許你的 IP

這是最常見的原因。即便你使用受控識別，網路還是要通。

• 如果你在 Azure 資源內執行：請到 SQL Server 的「網路 (Networking)」設定，確保 「允許 Azure 服務和資源存取此伺服器 (Allow Azure services and resources to access this server)」 有被勾選。
• 如果你在公司內網執行：請確認你的公用 IP 已加入 SQL Server 的防火牆白名單。

2. 強制使用 TLS 1.2

Azure SQL 預設要求 TLS 1.2。如果你的 Python 環境或 ODBC 驅動程式版本太舊，握手時會因為加密協定不匹配而被中斷。

• 解決方法：確保你的連線字串中有 Encrypt=yes;（你已經有了）。
• 檢查驅動：確認你安裝的是 ODBC Driver 18 for SQL Server。注意：Driver 18 預設會強制驗證證書，如果你沒有設定憑證，請試著在連線字串加上 TrustServerCertificate=yes; 測試看看。

3. ODBC Driver 18 的「預設加密」改變

如果你是從 Driver 17 升級到 18，Driver 18 的預設行為變更了。請嘗試將連線字串稍微修改如下：

Python

connection_string = (
    f"DRIVER={driver};"
    f"SERVER={server};"
    f"DATABASE={database};"
    "Authentication=ActiveDirectoryMsi;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # 先暫時改成 yes 測試是否為證書握手失敗
    "Connection Timeout=30;"
)

關鍵排除步驟（Debug Check）

1. 測試工具連線：你在 Azure Portal 上的 「查詢編輯器 (Query Editor)」 現在能正常進去嗎？
   • 如果連 Query Editor 都進不去，那是資料庫本身的網路/防火牆設定問題。
2. 確認受控識別是否已成功建立 User：
   • 你剛才在嘗試 CREATE USER 時失敗了，這代表受控識別的身分還沒進到資料庫。
   • 重要：如果 CREATE USER 沒成功，Authentication=ActiveDirectoryMsi 就絕對連不上。

目前的卡點建議：

先解決 CREATE USER 的問題。請確認你是用 「Microsoft Entra 管理員」 的帳號登入 Query Editor。只有管理員有權限執行 FROM EXTERNAL PROVIDER 的指令。

微軟現在有個超讚的設定，可以把 Azure SQL 資料庫變成 僅限 Microsoft Entra ID 驗證。這聽起來很專業，其實就是把傳統的帳號密碼大門關起來，規定大家只能用正式的微軟雲端帳號登入。

停用本地驗證方法並僅允許 Azure Active Directory 驗證，可確保只有 Azure Active Directory 識別身分才能存取 Azure SQL Database，以提升安全性。

這樣做有什麼好處呢？

• 第一個好處是統一管理。所有的權限都歸雲端帳號管，不用在資料庫裡建一堆帳號。
• 再來是安全性大升級！因為雲端帳號可以開啟手機簡訊或 APP 的多重驗證，駭客就算偷到密碼也進不來！

操作起來其實很簡單，不論你是習慣打指令還是用滑鼠點網頁都能搞定。

如果你是用圖形網頁操作，只要在建立資料庫的時候，去 身份驗證 分頁點一下 僅限 Microsoft Entra 驗證。

接著搜尋你自己的帳號，把它設成 管理員 就大功告成。

設定完記得測試看看，這時候你會發現原本的 SQL 舊帳號已經被 封鎖 沒辦法用了，一定要改用微軟帳號才能進去。

我覺得這功能真的超方便！以前要記一堆資料庫密碼真的很痛苦，現在只要保護好一個主帳號就好。

把複雜的事情變簡單，而且還更安全，這絕對是現代開發者必學的懶人自保術呀！

既然程式是跑在 Docker 裡，沒辦法手動點選視窗，那我們就要幫程式申請一張「專屬通行證」，也就是 Client Secret 。

這張通行證要在 Azure 入口網站（Azure Portal）裡面產生，步驟其實很簡單，就像是在幫你的程式辦身分證一樣：

第一步：註冊應用程式

首先去 Azure Portal 搜尋「應用程式註冊」（App Registrations）:
https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade

點進去後選「新註冊」。幫你的程式取個名字，然後按註冊就好。這時候你會看到一個「應用程式 (用戶端) 識別碼」，這就是連線字串裡的 Client ID 。

第二步：產生秘密金鑰

在左邊選單找到「憑證與密碼」，點進去後選「用戶端密碼」，接著按「新用戶端密碼」。你可以設定這組密碼多久會過期。

第三步：立刻存檔

按下的那一刻，畫面會出現一串長長的字，那就是 Client Secret。記得這時候一定要趕快複製存起來！因為一旦離開這個畫面，系統就會把它遮起來，你再也看不到了，只能重新再產生一個 。

最後別忘了，還要回到你的 SQL Server 裡面，把這個應用程式的名字加進去並給它權限，你的程式才能順利進門。

我覺得這種做法雖然多了一點步驟，但把權限跟程式碼分開管理，程式碼裡不再放死板板的密碼，而是改用這種可以隨時更換、受雲端監控的通行證。

這樣一來，不只開發起來更優雅，安全等級也是直接拉滿，這才是專業開發者的懶人自保術呀

你知道除了手動複製，其實還有更安全的方法來管理這些秘密金鑰嗎？

既然都聊到這了，那一定要跟你分享進階版的絕招！

雖然把 Client Secret 存在 Docker 的環境變數裡已經比以前進步，但對追求極致安全的工程師來說，這還不夠。因為金鑰還是存在某個地方，萬一主機被攻破，祕密還是會外流。

這時候，我們可以用 Azure 提供的一種超神科技，叫做受控識別（Managed Identity）。

這概念就像是你不用再幫程式辦身分證了，而是直接讓 Azure 認得這台 虛擬機 或 容器 服務本身。當程式要去連資料庫時，它會直接跟 Azure 說：「嘿，我是你家養的容器，讓我進去吧！」

簡單來說，更安全的作法有兩種：

一、使用受控識別（最推薦）

這就像是 刷臉認證。你只要在 Azure 平台上把你的服務（例如 Azure Container Instances）開啟 受控識別 功能，並在 SQL 資料庫裡授權給它。

這時候 Python 的連線字串就會變得超乾淨，完全不需要 UID 也不需要 PWD：

driver = {ODBC Driver 18 for SQL Server}
connection_string = (
　f"DRIVER={driver};"
　f"SERVER={server},{port};"
　f"DATABASE={database};"
　"Authentication=ActiveDirectoryMSI;"
　"Encrypt=yes;"
　"TrustServerCertificate=no;"
　"Connection Timeout=30;"
)

這真的是 懶人包 的極致，程式碼裡完全沒有任何祕密，安全性滿分！

二、使用 Azure Key Vault

如果你還是需要用 Client Secret，可以把它藏在 雲端保險箱（Key Vault）裡面。

程式執行時才去保險箱領鑰匙，而不是直接把鑰匙貼在門口。這樣就算別人看到你的程式碼或 Docker 設定，也拿不到真正的密碼。

範例程式碼：

driver = {ODBC Driver 18 for SQL Server}
connection_string = (
　f"DRIVER={driver};"
　f"SERVER={server},{port};"
　f"DATABASE={database};"
　f"UID={client_id};"
　f"PWD={client_secret};"
　"Authentication=ActiveDirectoryServicePrincipal;"
　"Encrypt=yes;"
　"TrustServerCertificate=no;"
　"Connection Timeout=30;"
)

• 關鍵改版：我們把原本放「帳號」的地方換成 應用程式 ID（UID），把原本放「密碼」的地方換成 秘密金鑰（PWD）。
• 認證模式：這行 Authentication=ActiveDirectoryServicePrincipal 是最關鍵的！它就像是跟資料庫打暗號，說：「嘿！我是用程式身分來敲門的，不是真人喔！」
• 安全提醒：連線字串裡的 Encrypt=yes 建議要留著，這樣資料在傳輸過程中才會被加密，就像是幫資料坐上防彈運鈔車一樣安全。

我的小小建議：

我覺得最高境界，就是根本不要持有秘密。

當我們用受控識別（Managed Identity）的時候，身為開發者的我們連密碼長什麼樣子都不知道。不用擔心密碼過期、不用定期更換，更不用怕不小心把密碼推到 GitHub 上面去。

這種把 安全性 融入到環境架構裡的作法，不只讓開發過程變得超清爽，心裡也會覺得非常踏實，這才是真正的優雅開發呀！

這種 不用記密碼 的生活，是不是聽起來就很吸引人呢？

請注意，ODBC Driver 18 預設啟用了加密連線（Encrypt=yes），這與舊版本（v17）不同，連線時可能需要調整連線字串。

第一步：安裝 Microsoft ODBC Driver 18

請根據你的 Ubuntu 版本執行以下指令（適用於 20.04, 22.04, 24.04）：

導入 Microsoft 公鑰與來源清單

# 取得 Ubuntu 版本號 (如 22.04)
UBUNTU_VERSION=$(lsb_release -rs)

# 下載 Microsoft GPG 金鑰
curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc

# 加入 Microsoft Ubuntu 套件庫
curl https://packages.microsoft.com/config/ubuntu/$UBUNTU_VERSION/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list

安裝驅動程式與開發標頭檔

sudo apt-get update

ACCEPT_EULA=Y 會自動同意授權合約

sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

上面這行在 Ubuntu 26.04 會出錯, 錯誤訊息:

E: The repository 'https://packages.microsoft.com/ubuntu/24.04/prod noble InRelease' is not signed.

This is a classic “security handshake” failure. Even though you added the repository link, apt is refusing to trust it because it can’t verify the digital signature. This usually happens if the GPG key wasn’t imported correctly or if there’s a conflict with how the key is stored in newer versions of Ubuntu (like 24.04 “Noble”).

To fix this, we need to manually fetch the key and ensure it’s placed where apt expects it for that specific repository.

1. Clear the “Bad” List

First, let’s remove the entry that is causing the error so we can start fresh:

Bash

sudo rm /etc/apt/sources.list.d/mssql-release.list

2. Properly Import the GPG Key

Ubuntu 24.04 is stricter about GPG keys. Instead of using apt-key (which is deprecated), use this method to download and de-armor the key:

Bash

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg

3. Add the Repository with the Key Reference

Now, re-add the repository, but this time we will explicitly tell apt to use the keyring we just created to verify this specific URL:

Bash

echo "deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/24.04/prod noble main" | sudo tee /etc/apt/sources.list.d/mssql-release.list

4. Update and Install

Now the signature check should pass:

Bash

sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

What went wrong?

In modern Linux distributions, “un-signed” repositories are blocked by default to prevent “man-in-the-middle” attacks where someone could inject malicious software into your update stream. By using the signed-by flag in the .list file, you are creating a direct trust link between the Microsoft URL and the Microsoft GPG key you just downloaded.

One quick check: Are you definitely on Ubuntu 24.04? You can verify with lsb_release -a. If you are actually on 22.04, just swap the “24.04” and “noble” parts of the commands above with “22.04” and “jammy”.

（選填）安裝 SQL Server 命令列工具 (sqlcmd/bcp)

sudo ACCEPT_EULA=Y apt-get install -y mssql-tools18
echo 'export PATH="$PATH:/opt/mssql-tools18/bin"' >> ~/.bashrc
source ~/.bashrc

第二步：安裝 Python 套件

在你的 Python 虛擬環境中安裝 pyodbc：

pip install pyodbc

錯誤訊息:

azureuser@vmptprodjpe001:~$ pip install pyodbc
error: externally-managed-environment

解決方法：建立虛擬環境

請按照以下步驟操作：

先確保系統有安裝建立虛擬環境的工具：

sudo apt update 
sudo apt install python3-venv python3-full

在你的專案目錄下建立一個名為 venv 的虛擬環境：

python3 -m venv venv

啟動虛擬環境：

source venv/bin/activate

啟動後，你會發現指令列開頭多了 (venv) 的字樣，這時就可以放心安裝套件了：

pip install pyodbc

第三步：Python 程式碼範例與注意事項

由於 ODBC 18 預設強制加密，如果你的 Azure SQL 伺服器證書不是由受信任的授權單位簽發的（或者你在本地測試），你可能需要在連線字串中加入 TrustServerCertificate=yes。

import pyodbc

# 請替換成你的 Azure SQL 資訊
server = 'your_server.database.windows.net'
database = 'your_db'
username = 'your_username'
password = 'your_password'

# 注意 Driver 名稱必須精確匹配：{ODBC Driver 18 for SQL Server}
conn_str = (
    f"DRIVER={{ODBC Driver 18 for SQL Server}};"
    f"SERVER={server};"
    f"DATABASE={database};"
    f"UID={username};"
    f"PWD={password};"
    "Encrypt=yes;"
    "TrustServerCertificate=no;" # 若連線失敗可改為 yes 測試，但在正式環境建議保持 no
    "Connection Timeout=30;"
)

try:
    conn = pyodbc.connect(conn_str)
    cursor = conn.cursor()
    cursor.execute("SELECT @@version;")
    row = cursor.fetchone()
    print(f"Connected! SQL Server Version: {row[0]}")
except Exception as e:
    print(f"Error: {e}")

常見問題排除

• 找不到驅動程式：執行 odbcinst -q -d。你應該會看到 [ODBC Driver 18 for SQL Server]。如果沒有，請確認第一步安裝是否成功。
• SSL/TLS 錯誤：Azure SQL 要求 TLS 1.2 以上版本。Ubuntu 20.04+ 通常預設支援，但如果你在連線時遇到證書驗證錯誤，請檢查 Azure SQL 的防火牆設定，並確認 TrustServerCertificate 的設定。
• 權限問題：在 Azure VM 上，確保網路安全性群組 (NSG) 已允許 1433 埠通訊，且 Azure SQL 的防火牆已將該 VM 的公用 IP 加入白名單。

Error

W: OpenPGP signature verification failed: https://packages.microsoft.com/ubuntu/26.04/prod resolute InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY EE4D7792F748182B
E: The repository 'https://packages.microsoft.com/ubuntu/26.04/prod resolute InRelease' is not signed.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.

看來在 Ubuntu 24.04 (Noble) 上，系統沒能正確識別或找到你剛才匯入的 Microsoft GPG 金鑰。這通常是因為金鑰存放路徑與來源清單（.list）中定義的路徑不一致導致的。

從你的錯誤訊息看，noble InRelease 找不到金鑰 EB3E94ADBE1229CF。

解決方案

請按照以下步驟重新匯入金鑰並修正路徑：

1. 下載並轉換金鑰格式

Ubuntu 24.04 偏好使用 .gpg 格式存放在 /usr/share/keyrings/。

# 下載並將金鑰轉換為 gpg 格式存放到指定位置
curl -sSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor | sudo tee /usr/share/keyrings/microsoft-prod.gpg > /dev/null

2. 更新來源清單 (Source List)

確保你的 mssql-release.list 指向的是正確的金鑰路徑（剛才建立的那個）：

echo "deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/24.04/prod noble main" | sudo tee /etc/apt/sources.list.d/mssql-release.list

3. 再次執行安裝

現在更新索引，這一次應該不會報 GPG 錯誤了：

sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

驗證安裝結果

安裝完成後，你可以執行這個指令確認驅動程式已經就緒：

odbcinst -q -d -n "ODBC Driver 18 for SQL Server"

如果出現驅動程式的路徑資訊，就代表你成功了！接著就可以繼續用 pip install pyodbc 進行 Python 開發。

要在 Ubuntu 終端機直接測試連線，我們通常會使用 sqlcmd (隨 mssql-tools18 安裝) 或者使用 isql (unixODBC 自帶工具)。

由於你安裝的是 ODBC Driver 18，請特別注意連線字串中的加密選項。

方法一：使用 isql 進行快速測試

isql 是 unixODBC 提供的工具，適合用來驗證驅動程式是否能正確與資料庫握手。

請在終端機輸入以下指令（將參數直接寫在連線字串中）：

# -v 代表 verbose (詳細輸出)，可以幫你判斷錯誤原因
# 注意：ODBC 18 預設強制加密，若伺服器憑證未經第三方認證，需加上 TrustServerCertificate=yes
isql -v -k "DRIVER={ODBC Driver 18 for SQL Server};SERVER=1.2.3.4,1433;DATABASE=YOUR_DB;UID=userid;PWD=userpwd;Encrypt=yes;TrustServerCertificate=yes"

• 如果成功，你會看到 Connected! 提示。
• 輸入 quit 即可結束連線。

方法二：使用 sqlcmd (Microsoft 官方工具)

如果你之前有安裝 mssql-tools18，這是最推薦的測試方式：

sqlcmd -S 1.2.3.4,1433 -d YOUR_DB -U userid -P 'userpwd' -C

• 參數 -C 代表 TrustServerCertificate（信任伺服器憑證）。
• 注意：如果密碼包含特殊字元，請用單引號 ' ' 包起來。

疑難排解：連線失敗的常見原因

1. Network Timeout (連線逾時)：
   • 檢查 Azure NSG：確保你的 Azure VM 出站規則 (Outbound) 允許 1433 埠。
   • 檢查目標伺服器：1.2.x.x 的 IP，請確認該伺服器防火牆是否有將你的 Azure VM 公用 IP 加入白名單。
2. SSL Provider 錯誤 (憑證問題)：
   • 這是 ODBC 18 最常見的問題。如果沒加 TrustServerCertificate=yes (或 isql 中的參數)，連線會因為無法驗證憑證而中斷。
3. Login Failed：
   • 請確認資料庫名稱 YOUR_DB 與帳密無誤。

Python 程式碼快速驗證

如果你已經進入了虛擬環境並安裝了 pyodbc，可以用這段代碼直接測試：

Python

import pyodbc

conn_str = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    "SERVER=1.2.3.4,1433;"
    "DATABASE=YOUR_DB;"
    "UID=userid;"
    "PWD=userpwd;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"
)

try:
    with pyodbc.connect(conn_str, timeout=5) as conn:
        print("連線成功！")
        cursor = conn.cursor()
        cursor.execute("SELECT TOP 1 name FROM sys.databases")
        print(f"資料庫清單測試: {cursor.fetchone()}")
except Exception as e:
    print(f"連線失敗原因: {e}")

你的連線測試結果出現什麼錯誤訊息嗎？

在 Go 語言開發後端並對接 MSSQL 時，分頁（Pagination）是一個非常經典的效能優化課題。對於 Cursor-based（指標式） 與 Offset-based（偏移量式，即你提到的下兩次 SQL） 的選擇，取決於你的業務場景（如：後台管理系統 vs. 無限捲動的 App）。

以下是詳細的比較、實作建議與常見坑點。

一、 分頁方案深度對比

1. Offset-based Paging (兩次 SQL 請求)

這是最常見的作法：先 SELECT COUNT(*) 算總數，再用 OFFSET / FETCH 取資料。

• 實作方式 (MSSQL 2012+)：SQL-- 第 1 次：拿總筆數 SELECT COUNT(*) FROM Orders WHERE Status = 1; -- 第 2 次：拿分頁資料 SELECT * FROM Orders WHERE Status = 1 ORDER BY OrderID OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY;
• 優點：
  • 支援跳頁： 使用者可以直接點擊「第 5 頁」。
  • 前端友善： 容易計算總頁數、顯示剩餘頁數。
• 缺點：
  • 效能問題： 當 OFFSET 很大時（例如萬級跳頁），資料庫必須掃描並丟棄前面的資料，效能劇降。
  • 資料飄移： 在分頁過程中若有新資料插入，使用者可能會看到重複的資料。

2. Cursor-based Paging (Seek Method)

不使用偏移量，而是根據上一頁最後一筆資料的唯一標識（如 ID 或時間戳）來找下一頁。

• 實作方式：SQL-- 假設上一頁最後一個 ID 是 500 SELECT TOP 10 * FROM Orders WHERE Status = 1 AND OrderID > 500 ORDER BY OrderID ASC;
• 優點：
  • 高效能： 無論翻到多深，效能幾乎一致，因為它利用索引直接定位。
  • 穩定性： 不會因為資料插入/刪除導致看到重複或遺漏資料。
• 缺點：
  • 無法跳頁： 只能「下一頁」或「上一頁」，適合「載入更多」或無限捲動。
  • 排序限制： 排序欄位必須具有唯一性（或搭配主鍵排序）。

二、 比較總覽表

三、 其他實作解決辦法與第三方套件

在 Go 的生態系中，你不需要從零開始寫 SQL，可以利用以下套件處理：

1. GORM (最流行的 ORM)

GORM 內建了分頁的封裝，但通常是基於 Offset 的。

• Offset 實作： db.Limit(10).Offset(20).Find(&users)
• 問題： 它不會自動幫你做 COUNT(*)，你通常需要自己寫一個 Wrapper 函數跑兩次查詢。

2. Ent (Facebook 出品的強型別 ORM)

Ent 對於分頁的 API 設計非常優雅，支援較複雜的查詢組合。

• 優點： 程式碼生成技術讓你的分頁查詢在編譯期就受檢查。

3. SQLX

如果你喜歡原生 SQL，sqlx 是首選。它沒有自動分頁功能，但能輕鬆將結果 Map 到 Struct。

四、 實作中遇到的常見問題與坑

1. MSSQL 的 ORDER BY 限制

在 MSSQL 中，使用 OFFSET / FETCH 必須搭配 ORDER BY。如果你沒寫 ORDER BY，SQL 會報錯。這在 Go 寫動態查詢時常被忽略。

2. COUNT(*) 的效能殺手

當資料量達到千萬級，SELECT COUNT(*) 會變得非常慢。

• 解決： 如果不要求精確總數，可以從 MSSQL 的系統表（sys.partitions）讀取近似值，或者快取總數（Cache）。

3. Deep Paging (深分頁) 攻擊

惡意使用者或爬蟲可能會請求 OFFSET 1000000，這會瞬間拖垮資料庫 IO。

• 解決： 強制限制最大跳頁數，或者超過一定頁數後強制切換為 Cursor 模式。

4. N+1 問題

在 Go 實作分頁時，如果拿到分頁後又在 Loop 裡查詢關聯資料，會導致效能崩潰。

• 解決： 使用 JOIN 或 Preload (Eager Loading)。

五、 最終建議

1. 一般管理後台： 使用 Offset-based。雖然它有兩次 SQL，但在資料量小於 10 萬筆時，使用者體驗最佳（因為能跳頁）。你可以寫一個 Go Pagination Helper 函式來統一回傳 {total, page, data}。
2. 高流量 / 大數據 App： 務必使用 Cursor-based。
3. 效能折衷方案：
   • 先查出 ID 清單（Covering Index），再用 ID 去 IN 查資料。
   • SELECT COUNT(*) 加上快取（例如 Redis 存 5 分鐘），不需要每次翻頁都重新算總數。

從 MSSQL 切換到 MySQL 或 PostgreSQL，對於 Go 後端開發來說，最直接的影響在於 SQL 語法（Dialect）、參數佔位符以及底層驅動的行為。

針對你關心的「分頁實作」，以下是切換後的詳細影響分析：

一、 語法差異：分頁關鍵字

這是最明顯的改變。雖然邏輯不變，但 SQL 字串必須重寫。

Cursor-based 的影響：

三者在 Cursor 模式下的 WHERE ID > ? LIMIT 10 語法幾乎完全一致。

二、 Go 程式碼層面的影響

1. SQL 參數佔位符 (Placeholders)

這是 Go 開發者最容易踩坑的地方，不同的驅動對參數的標示方式不同：

• MySQL: 使用問號 ?（例如：WHERE id = ?）
• PostgreSQL: 使用序號 $1, $2（例如：WHERE id = $1）
• MSSQL: 通常使用 @p1 或 ?（取決於驅動）

影響： 如果你寫的是原生 SQL，切換資料庫時，你必須修改所有的查詢字串。若使用 GORM 或 Ent，ORM 會自動幫你處理掉這個差異。

2. 驅動程式 (Drivers)

• MySQL: 常用 github.com/go-sql-driver/mysql。
• PostgreSQL: 推薦使用 github.com/jackc/pgx，效能與對功能（如 JSONB）的支援比舊的 lib/pq 好很多。

三、 效能與實作細節的影響

1. PostgreSQL 的 COUNT(*) 痛點

在分頁需要回傳「總筆數」時，PostgreSQL 的 COUNT(*) 通常比 MySQL 和 MSSQL 慢。

• 原因： 由於 PostgreSQL 的多版本並發控制 (MVCC) 機制，它必須掃描資料來確定哪些列對當前事務是「可見的」，無法像某些引擎一樣直接從元數據讀取。
• 解決： 在 PG 中，大數據量的分頁總數通常會改用 reliquary（估算值）或額外維護一個計數表。

2. MySQL 的大 Offset 效能

MySQL 在處理 LIMIT 100000, 10 時，效能損耗非常明顯。雖然這在所有 DB 都有發生，但 MySQL 的優化器在某些情況下處理「延遲關聯」（Late Row Lookups）的手法與 MSSQL 不同，需要手動優化。

3. 交易隔離級別 (Isolation Levels)

• MSSQL: 預設有時會發生讀寫鎖定衝突。
• PostgreSQL: 預設是 Read Committed，在處理高併發分頁時表現非常穩定。

四、 第三方套件的處理方案

如果你想讓系統在切換資料庫時更輕鬆，建議引入以下套件：

1. GORM (Object Relational Mapper)
   • 優點： 你只需更改初始化時的 gorm.Open(mysql.Open(dsn))，分頁程式碼 db.Offset(10).Limit(5) 完全不用動。
   • 缺點： 隱藏了底層細節，有時難以優化特定 DB 的特殊索引行為。
2. Masterminds/squirrel (SQL Builder)
   • 如果你不想用 ORM 但想解決佔位符問題，squirrel 可以幫你動態構建 SQL。
   • 它可以根據設定生成 ? 或 $1，讓你換 DB 時不用手改字串。
3. ozzo-dbx / sqlx
   • 輕量級封裝，雖然仍要寫 SQL，但簡化了將分頁結果 Map 到 Go Struct 的過程。

五、 總結建議

1. 如果你追求開發速度與靈活性： 切換到 PostgreSQL。它對進階資料型別（JSONB, Array）的支援極佳，且分頁效能穩定。Go 社群對 PG 的支持度（如 pgx 驅動）目前是最高的。
2. 如果你擔心遷移成本：
   • 若使用 ORM (GORM)：切換成本極低，只需調整配置。
   • 若使用 原生 SQL：建議先建立一個 QueryBuilder 層，將 LIMIT/OFFSET 的生成抽象化，否則手改數百個 ? 到 $1 會非常痛苦。
3. 分頁策略調整：
   • 無論換到哪種 DB，若資料量大，Cursor-based 永遠是首選。
   • 若必須用 Offset-based，請務必在切換後針對 COUNT(*) 進行壓力測試，尤其是 PostgreSQL。

既然你已經安裝了 Docker Desktop 和 Node.js，接下來可以按照以下步驟建立開發環境：

1. 專案目錄結構建議

首先，建議建立一個清晰的資料夾結構，將前端、後端與 Docker 設定分開：

Plaintext

my-app/
├── backend/           # FastAPI 程式碼
│   ├── main.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/          # React 程式碼
│   ├── src/
│   ├── package.json
│   └── Dockerfile
└── docker-compose.yml # 核心：同時啟動前後端與資料庫

2. 後端環境準備 (FastAPI)

在 backend/ 資料夾中，建立以下兩個核心檔案：

requirements.txt:

fastapi
uvicorn
sqlalchemy
psycopg2-binary  # 如果使用 PostgreSQL

Dockerfile:

Dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

Note: --reload 參數非常重要，它讓你修改代碼時，容器內的服務會自動重啟。

3. 前端環境準備 (React)

在 my-app/ 目錄下執行

npx create-react-app frontend

然後在 frontend/ 建立 Dockerfile:

Dockerfile

FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

4. 關鍵：配置 Docker Compose

這是將所有組件串聯起來的核心。在專案根目錄建立 docker-compose.yml：

YAML

services:
  db:
    image: postgres:15 # 以 PostgreSQL 為例
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydatabase
    ports:
      - "5432:5432"

  backend:
    build: ./backend
    volumes:
      - ./backend:/app # 掛載程式碼，實現即時更新
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://user:password@db:5432/mydatabase
    depends_on:
      - db

  frontend:
    build: ./frontend
    volumes:
      - ./frontend:/app
      - /app/node_modules # 避免本地 node_modules 覆蓋容器內的
    ports:
      - "3000:3000"
    stdin_open: true # 讓 React 偵測到開發終端

5. 開發工作流程

啟動環境：在根目錄開啟終端機（PowerShell 或 CMD），輸入：

docker-compose up --build

存取服務：

• 前端：http://localhost:3000
• 後端 API：http://localhost:8000
• API 文件 (Swagger)：http://localhost:8000/docs

連接資料庫：在 FastAPI 中，資料庫的連線主機名稱（Hostname）直接填寫 db（即 Compose 中的服務名稱），而非 localhost。

6. Azure 準備 (下一步建議)

由於你最終要上傳到 Azure，建議你現在可以先安裝 Azure CLI：

指令：

winget install -e --id Microsoft.AzureCLI

目的：這讓你能在本地端直接將 Docker Image 推送到 Azure Container Registry (ACR)，並部署到 Azure Container Apps 或 App Service。

溫馨提示：在 Windows 上開發時，建議將專案放在 WSL 2 (Ubuntu) 的檔案系統內（路徑通常是 \\wsl$\...），Docker 的讀寫效能會比在 Windows 原生路徑下快非常多。

移除 sqlalchemy, database 使用 microsoft sql server, 在 azure 上會換成azure sql

既然你要將資料庫從 PostgreSQL 換成 Microsoft SQL Server (本地開發) 與 Azure SQL (雲端部署)，並移除 SQLAlchemy 改用更輕量或原生的方式，我們的開發環境需要做一些關鍵調整。

在 Windows 上連接 SQL Server，通常建議使用 pyodbc 驅動程式。

1. 調整後的專案結構

結構保持不變，但 backend 的配置會有所不同：

my-app/
├── backend/
│   ├── main.py
│   ├── requirements.txt  # 加入 pyodbc
│   └── Dockerfile        # 需要安裝 SQL Server 驅動
├── frontend/             # React (Node.js)
└── docker-compose.yml    # 伺服器改為 MSSQL Edge 或 SQL Server

2. 後端環境 (FastAPI + MS SQL)

requirements.txt

fastapi
uvicorn
pyodbc

Dockerfile (關鍵修改)

連接 SQL Server 需要在 Linux 容器內安裝 Microsoft ODBC Driver。這部分的 Dockerfile 較為特殊：

Dockerfile

FROM python:3.11-slim

# 1. 安裝必要工具
RUN apt-get update && apt-get install -y \
    curl \
    gnupg2 \
    && rm -rf /var/lib/apt/lists/*

# 2. 下載並安裝 Microsoft ODBC Driver 18 (適用於 Debian 12/11)
RUN curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > /usr/share/keyrings/microsoft-prod.gpg \
    && curl https://packages.microsoft.com/config/debian/12/prod.list > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev \
    && rm -rf /var/lib/apt/lists/*

# 3. 設定工作目錄
WORKDIR /app

# 4. 安裝 Python 套件
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 5. 複製程式碼並啟動
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

3. Docker Compose 配置

我們在本地使用 mcr.microsoft.com/azure-sql-edge，它是專為輕量開發設計的 SQL Server 版本（支援 ARM 與 x64，且在 Docker 上跑得更快）。

docker-compose.yml:

YAML

services:
  db:
    image: mcr.microsoft.com/azure-sql-edge
    container_name: mssql_db
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "YourStrongPassword123!"
    ports:
      - "1433:1433"

  backend:
    build: ./backend
    volumes:
      - ./backend:/app
    ports:
      - "8000:8000"
    environment:
      # 注意：連接字串需包含 TrustServerCertificate=yes
      DB_CONNECTION_STRING: "DRIVER={ODBC Driver 18 for SQL Server};SERVER=db;DATABASE=master;UID=sa;PWD=YourStrongPassword123!;Encrypt=yes;TrustServerCertificate=yes"
    depends_on:
      - db

  frontend:
    build: ./frontend
    volumes:
      - ./frontend:/app
      - /app/node_modules
    ports:
      - "3000:3000"
    stdin_open: true

4. FastAPI 存取範例 (main.py)

不使用 SQLAlchemy，我們直接使用 pyodbc 進行查詢：

Python

from fastapi import FastAPI
import pyodbc
import os

app = FastAPI()

# 從環境變數讀取連線資訊
conn_str = os.getenv("DB_CONNECTION_STRING")

@app.get("/")
def read_root():
    try:
        conn = pyodbc.connect(conn_str)
        cursor = conn.cursor()
        cursor.execute("SELECT @@VERSION")
        row = cursor.fetchone()
        return {"database_version": row[0]}
    except Exception as e:
        return {"error": str(e)}

5. 開發建議與注意事項

• Azure SQL 的差異：當你部署到 Azure 時，只需修改 DB_CONNECTION_STRING 環境變數。Azure SQL 強制要求加密 (Encrypt=yes)，這也是為什麼我們在 Dockerfile 中安裝了最新版的 ODBC Driver 18。
• 防火牆：如果你在本地使用 SQL Server Management Studio (SSMS) 連接 Docker 裡的資料庫，伺服器名稱請填 127.0.0.1,1433。
• 前端 Proxy：在 React 的 package.json 中加入 "proxy": "http://backend:8000"，可以簡化前端呼叫 API 的程式碼，避免 CORS 問題。

要在 Windows 本地測試並推送到 Azure，流程主要分為 「本地聯動測試」 與 「雲端推送部署」 兩個階段。

1. 本地 Docker Desktop 測試

在本地測試時，最重要的是確保 跨容器通訊 正常（例如 React 如何抓到 FastAPI 的資料）。

執行測試指令

開啟 PowerShell 或終端機，進入專案根目錄（包含 docker-compose.yml 的地方）：

PowerShell

# 1. 啟動所有服務 (包含 MSSQL, Backend, Frontend)
docker-compose up --build

# 2. 如果要以後台模式執行
docker-compose up -d

如何驗證測試成功？

• API 測試：瀏覽 http://localhost:8000/docs，點擊 Execute 測試 API 是否能成功從 MSSQL 讀取資料。
• 前端測試：瀏覽 http://localhost:3000。
• 查看日誌：如果連線失敗，執行 docker-compose logs backend 查看 Python 的 pyodbc 報錯訊息。

2. 使用 Azure CLI 推送到 Azure Container Registry (ACR)

當本地測試沒問題後，你需要將 Image 推送到雲端倉庫。Azure 提供 ACR (Azure Container Registry) 來存放這些映像檔。

步驟 A：登入 Azure 並建立資源

首先，確保你已安裝 Azure CLI。

PowerShell

# 1. 登入 Azure
az login

# 2. 建立資源群組 (如果還沒有)
az group create --name MyResourceGroup --location eastasia

# 3. 建立 ACR (名稱必須是唯一且小寫)
az acr create --resource-group MyResourceGroup --name myuniqueacr --sku Basic

# 4. 登入 ACR 
az acr login --name myuniqueacr

步驟 B：標記並推送 Image

你需要將本地的 Image 給予一個符合 ACR 規範的「標籤 (Tag)」。

PowerShell

# 1. 取得 ACR 的登入伺服器名稱 (通常是 myuniqueacr.azurecr.io)
$ACR_SERVER = "myuniqueacr.azurecr.io"

# 2. 標記本地 Image (假設你在 compose 產生的 image 叫 my-app_backend)
docker tag my-app_backend $ACR_SERVER/fastapi-backend:v1
docker tag my-app_frontend $ACR_SERVER/react-frontend:v1

# 3. 推送到雲端
docker push $ACR_SERVER/fastapi-backend:v1
docker push $ACR_SERVER/react-frontend:v1

3. Azure 端的資料庫銜接

當你推送到 Azure 後，你的 FastAPI 需要改連 Azure SQL Database。

1. 建立 Azure SQL：在 Azure Portal 建立一個 SQL Database。
2. 防火牆設定：在 Azure SQL 的防火牆設定中，勾選 「允許 Azure 服務和資源存取此伺服器」。
3. 環境變數：在部署 Container（如使用 Azure Container Apps）時，將 DB_CONNECTION_STRING 改為 Azure SQL 的連線字串。

4. 懶人部署法：Azure Container Apps (推薦)

如果你不想管複雜的 Kubernetes，可以使用 Azure Container Apps，它支援多容器應用。

PowerShell

# 建立 Container App 環境並直接從 ACR 部署 (簡化指令範例)
az containerapp up --name my-fastapi-app `
  --resource-group MyResourceGroup `
  --image $ACR_SERVER/fastapi-backend:v1 `
  --environment 'MyEnv'

常見踩雷提醒：

• 晶片架構：如果你使用的是 Mac M1/M2 開發但推送到 Azure (x86_64)，打包時要加上 --platform linux/amd64。在 Windows 上開發則通常沒這個問題。
• MSSQL 密碼：Azure SQL 的密碼要求較嚴格，本地測試時建議就先用複雜密碼。

錯誤訊息 failed to read dockerfile: open Dockerfile: no such file or directory 非常直觀：Docker 在你指定的路徑下找不到 Dockerfile。

這通常是因為 docker-compose.yml 裡面的 build 路徑設定，與你實際資料夾結構不一致造成的。

1. 檢查你的目錄結構

請確認你的資料夾長得像這樣（注意大小寫，Linux 容器對大小寫很敏感）：

Plaintext

C:\max\work\policy-recommends\my-fast-app\
├── docker-compose.yml
├── backend/
│   └── Dockerfile      <-- 確認這個檔案存在，且副檔名沒有被隱藏 (不是 Dockerfile.txt)
└── frontend/
    └── Dockerfile      <-- 確認這個檔案存在

重新執行的正確姿勢

修正路徑或檔案後，建議先清理一下快取再執行：

PowerShell

# 強制重新檢查 build context 並建立
docker-compose build --no-cache

# 啟動
docker-compose up

如何推送到 Azure ACR (完整指令流)

等你本地 docker-compose up 成功執行後，按照以下順序推送到 Azure：

PowerShell

# 1. 登入 Azure (會跳出瀏覽器)
az login

# 2. 登入你的 ACR (假設名字叫 myacr123)
az acr login --name myacr123

# 3. 取得本地剛剛 build 好的 Image ID 或名稱
# 執行 docker images 查看剛剛產生的 image 名稱
docker images

# 4. 幫 Image 打上標籤 (Tag)
# 格式：docker tag [本地名稱] [ACR名稱].azurecr.io/[映像檔名稱]:[版本]
docker tag my-fast-app-backend myacr123.azurecr.io/fastapi-api:v1

# 5. 推送
docker push myacr123.azurecr.io/fastapi-api:v1

針對 React (Node.js) 前端，在開發環境與生產環境（Azure）的需求不同。為了讓你現在能在 Windows Local 成功執行 docker-compose up，我們採用開發模式的 Dockerfile。

請在 frontend/ 資料夾下建立一個名為 Dockerfile 的檔案（不含副檔名），內容如下：

Dockerfile

# 1. 使用 Node.js 官方映像檔 (建議版本 18 或 20)
FROM node:20

# 2. 設定容器內的工作目錄
WORKDIR /app

# 3. 先複製 package.json 與 package-lock.json (利用 Docker 快取機制)
COPY package*.json ./

# 4. 安裝相依套件
RUN npm install

# 5. 複製其餘的所有程式碼到容器內
COPY . .

# 6. React 預設開發埠號為 3000
EXPOSE 3000

# 7. 啟動 React 開發伺服器
# 使用 --host 0.0.0.0 是為了讓容器外的瀏覽器能存取
CMD ["npm", "start"]

兩個關鍵注意事項 (Windows 平台)

1. .dockerignore 檔案

在 frontend/ 資料夾內建立一個 .dockerignore 檔案。這能防止將本地巨大的 node_modules 複製進容器，導致 Build 速度極慢或產生錯誤。

內容如下：

node_modules
build
.git
*.md

2. 解決 Docker 抓不到檔案變更 (Hot Reload)

在 Windows 上使用 Docker Desktop 時，有時 React 的熱更新（存檔後網頁自動重新整理）會失效。如果發生這種情況，請在 frontend/ 資料夾建立一個 .env 檔案，加入以下內容：

CHOKIDAR_USEPOLLING=true

接下來的操作步驟：

檢查 package.json：確保你的 frontend/ 資料夾內確實有 package.json
（通常是執行 npx create-react-app . 產生的）。

執行 Build：

docker-compose build frontend

啟動服務：

docker-compose up frontend

如果你的 React 是用 Vite 建立的（現在比較流行），CMD 可能需要改成 npm run dev -- --host，你需要我確認你的 package.json 腳本內容嗎？

既然你的資料夾目前是空白的，我們來快速建立一個**「全端連通」**的範例。這個範例會讓 React 前端呼叫 FastAPI 後端，而後端會從 MSSQL 資料庫讀取版本資訊。

請依照以下檔案內容填入你的資料夾：

1. 後端 (backend/main.py)

這是一個簡單的 API，它會嘗試連線資料庫並回傳 SQL Server 的版本。

Python

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
import pyodbc
import os

app = FastAPI()

# 允許前端跨域存取 (CORS)
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/api/status")
def get_status():
    conn_str = os.getenv("DB_CONNECTION_STRING")
    try:
        # 建立連線
        conn = pyodbc.connect(conn_str, timeout=5)
        cursor = conn.cursor()
        cursor.execute("SELECT @@VERSION")
        db_version = cursor.fetchone()[0]
        conn.close()
        return {
            "status": "Connected",
            "database": "Microsoft SQL Server",
            "version": db_version
        }
    except Exception as e:
        return {
            "status": "Error",
            "message": str(e)
        }

@app.get("/")
def read_root():
    return {"message": "FastAPI is running!"}

2. 前端 (frontend/src/App.js)

我們簡單用 fetch 來抓取後端的 API 資料。

JavaScript

import React, { useEffect, useState } from 'react';

function App() {
  const [data, setData] = useState({ status: "Loading...", version: "" });

  useEffect(() => {
    // 指向後端容器的對外 Port
    fetch('http://localhost:8000/api/status')
      .then(response => response.json())
      .then(json => setData(json))
      .catch(err => setData({ status: "Error", message: "Cannot connect to API" }));
  }, []);

  return (
    <div style={{ textAlign: 'center', marginTop: '50px', fontFamily: 'sans-serif' }}>
      <h1>React + FastAPI + MSSQL</h1>
      <div style={{ border: '1px solid #ccc', padding: '20px', display: 'inline-block' }}>
        <p><strong>DB Status:</strong> {data.status}</p>
        {data.version && <p><strong>DB Version:</strong> {data.version}</p>}
        {data.message && <p style={{ color: 'red' }}>{data.message}</p>}
      </div>
    </div>
  );
}

export default App;

3. 前端必要設定 (frontend/package.json)

如果你還沒建立 React 專案，最簡單的方式是在 frontend/ 資料夾下建立這個檔案：

JSON

{
  "name": "frontend",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build"
  },
  "eslintConfig": {
    "extends": [
      "react-app"
    ]
  },
  "browserslist": {
    "production": [">0.2%", "not dead", "not op_mini all"],
    "development": ["last 1 chrome version", "last 1 firefox version", "last 1 safari version"]
  }
}

4. 啟動與驗證

現在再次執行：

docker-compose up --build

驗證方式：

1. 等待 MSSQL 啟動：SQL Server 啟動較慢（約 20-30 秒），剛開始 API 可能會報錯，請重新整理頁面。
2. 開啟瀏覽器：輸入 http://localhost:3000。
3. 預期結果：你應該會看到網頁顯示 “DB Status: Connected” 以及 “Microsoft SQL Azure…” 的版本文字。

小提示：

由於我們是在 Docker 外部的瀏覽器看網頁，前端代碼 fetch('http://localhost:8000/api/status') 使用 localhost 是正確的。

但如果是後端要找資料庫，docker-compose.yml 裡的連線字串必須寫 SERVER=db。

這個錯誤 "/requirements.txt": not found 代表 Docker 在執行 COPY requirements.txt . 這行指令時，在你的 backend/ 資料夾 裡找不到這個檔案。

在 Docker 的世界裡，COPY 指令尋找檔案的起點是 docker-compose.yml 中定義的 context 路徑。

1. 解決方法：建立必要的相依檔案

請確保你的目錄結構與檔案名稱完全一致（注意大小寫）：

在 \my-fast-app\backend\ 資料夾下，建立一個名為 requirements.txt 的檔案，內容如下：

fastapi
uvicorn
pyodbc

2. 完整檢查清單

如果還是報錯，請檢查以下三點：

檔案位置：requirements.txt 必須與 backend/Dockerfile 放在同一個資料夾內。

副檔名陷阱：在 Windows 中，檔案可能會被命名為 requirements.txt.txt（如果你開啟了隱藏已知檔案類型的擴充名）。請確認檔名只有一個 .txt。

Docker Compose 路徑：確認你的 docker-compose.yml 是這樣寫的：

backend:
 build: ./backend 
# 這代表 Docker 會去 backend 資料夾找 Dockerfile 和 requirements.txt

3. 下一步：再次執行

修正檔案後，請執行以下指令（加上 --no-cache 確保它不會抓到舊的錯誤暫存）：

PowerShell

docker-compose build --no-cache
docker-compose up

給你的開發小秘訣

由於你之後要推送到 Azure，現在建立這些檔案時，可以順便檢查你的 frontend/ 資料夾是否也已經準備好了：

1. frontend/package.json (前一個回答提供的內容)
2. frontend/src/App.js (前一個回答提供的內容)
3. frontend/Dockerfile

如果 backend 編譯成功了，但換成 frontend 報錯 package.json not found，處理方式是一樣的：確保檔案真的躺在 frontend/ 資料夾裡。

這是一個完整的測試指南，幫助你驗證 React (前端)、FastAPI (後端) 與 SQL Server (資料庫) 這三個組件是否已經成功串聯。

1. 檢查容器運行狀態

首先，確保所有服務都已啟動。在 Windows PowerShell 執行：

PowerShell

docker ps

檢查重點： 你應該會看到三個容器，且狀態（STATUS）顯示為 Up。如果看到 Exited，代表該服務啟動失敗，請執行 docker-compose logs [服務名稱] 查看報錯。

2. 測試後端 API (FastAPI)

FastAPI 自帶強大的 Swagger UI，這是測試資料庫連線最快的方法。

• 網址： 打開瀏覽器輸入 http://localhost:8000/docs
• 操作： 1. 找到我們寫的 GET /api/status 端點。2. 點擊 “Try it out”，然後點擊 “Execute”。
• 預期結果：
  • Code 200 (Success)：你會看到包含 SQL Server 版本資訊的 JSON 字串。這代表 FastAPI -> MSSQL 通訊正常。
  • Error 500：通常是資料庫密碼錯誤或 Driver 設定問題。
  • 連線逾時：SQL Server 啟動較慢（通常需要 30 秒），請稍等片刻再試。

3. 測試前端網頁 (React)

現在測試前端是否能成功抓到後端的資料。

• 網址： 打開瀏覽器輸入 http://localhost:3000
• 操作： 觀察網頁顯示的內容。
• 預期結果：
  • 畫面顯示 “DB Status: Connected”：恭喜！整個全端流程 瀏覽器 -> React -> FastAPI -> MSSQL 全部打通。
  • 畫面卡在 “Loading…” 或顯示 “Error”：
    1. 按下 F12 打開開發者工具。
    2. 切換到 Console (主控台)。如果是 CORS 報錯，代表 FastAPI 的中間件設定有誤；如果是 404，請確認 API 路徑是否正確。

4. 測試資料庫 (SQL Server)

如果你懷疑資料庫根本沒動，可以獨立測試它。

查看日誌：

docker logs mssql_db 

尋找這一行：SQL Server is now ready for client connections.。

外部連線：如果你電腦有安裝 SSMS (SQL Server Management Studio) 或 Azure Data Studio，可以直接連線：

伺服器： 127.0.0.1,1433

帳號： sa

密碼： YourStrongPassword123! (你在 compose 檔設定的那組)

5. 總結連線邏輯 (除錯關鍵)

在 Docker 環境下，連線位址會因為「誰發起請求」而不同：

常見問題排除

• 修改代碼後沒反應？ 確保 docker-compose.yml 有設定 volumes 掛載，這樣你在 Windows 修改程式碼時，容器內才會同步更新。
• 無法連線資料庫？ 請檢查 main.py 裡的連線字串是否包含 TrustServerCertificate=yes，因為自架的 Docker SQL Server 通常沒有正式憑證。

如果你現在測試成功了，下一步我們是否要來練習如何將這兩個 Image (Frontend/Backend) 推送到 Azure ACR 並準備部署？

port 3000 改 8080

沒問題！在 Windows 上，3000 埠確實常被一些系統服務（如某些版本的 Windows 服務或開發工具）佔用。將前端改為 8080 是一個好選擇。

請依照以下三個步驟修改設定：

1. 修改 docker-compose.yml

將 frontend 服務的 ports 對應改為 8080:3000。這代表：瀏覽器輸入 8080，會轉發到容器內的 3000。

YAML

  frontend:
    build: ./frontend
    volumes:
      - ./frontend:/app
      - /app/node_modules
    ports:
      - "8080:3000"  # 修改這裡：外部 8080 -> 內部 3000
    stdin_open: true
    environment:
      - WDS_SOCKET_PORT=8080 # 確保 React 的熱更新 (Hot Reload) 也能走 8080

2. 修改前端程式碼 (frontend/src/App.js)

如果你的 React 程式碼中原本有寫死後端網址，請確認它依然指向 8000（後端沒改）。

但為了確保瀏覽器不會因為埠號變更而產生安全性阻攔，請檢查 App.js 中的 fetch：

JavaScript

// 確保後端依然是 8000
fetch('http://localhost:8000/api/status')

3. 重新啟動服務

由於你修改了 docker-compose.yml 的結構，建議先停止舊的容器再重新啟動：

PowerShell

# 停止並移除舊的容器
docker-compose down

# 重新啟動
docker-compose up

如何驗證？

1. 前端網頁：打開瀏覽器訪問 http://localhost:8080。
2. 後端 API：訪問 http://localhost:8000/docs。

專業小撇步：如果連 8080 也被佔用？

如果在啟動時依然看到 bind: An attempt was made...，這代表 8080 也有人在用。你可以執行這個指令來徹底「殺掉」佔用者：

PowerShell

# 尋找誰在用 8080 (在管理員模式的 PowerShell)
$proc = Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue
if($proc) { Stop-Process -Id $proc.OwningProcess -Force }

現在你可以試試看 http://localhost:8080 能不能看到 React 畫面了。如果畫面出來了但顯示 “Connection Error”，我們再來調整 FastAPI 的 CORS 設定！

以下是 DTU – Basic 在開發校務建言系統時，可能「不夠用」的幾種情況：

1. 併發連線數（Max Concurrent Workers）限制

這是 Basic 最致命的短板。

• 限制：Basic 僅支援 30 個併發工作執行緒。
• 情境：如果校方發出一封全校 Email 邀請大家來建言，瞬間有 50 位同學點開網頁，資料庫會立刻排隊甚至報錯（Timeouts），導致系統看起來像掛掉了。
• 建議：若預期會有瞬間高流量（如開會期間、校園新聞發布），Basic 可能無法負荷。

2. IOPS 與資料吞吐量效能

• 限制：Basic 的 I/O 效能非常基礎。
• 情境：雖然你將附件存在 Blob Storage（這是非常正確的作法！），但資料庫仍需處理建言內容的 全文檢索 或 複雜查詢（例如：管理員要篩選「過去一年、所有關於總務處、且狀態為未處理」的建言）。當資料筆數累積到幾千筆以上時，這種分群彙整（Group By）的查詢速度會變得很慢。

3. 資料庫大小上限

• 限制：Basic 的硬碟空間上限通常只有 2 GB。
• 情境：雖然附件在 Blob，但如果建言系統包含大量文字回覆、系統 Log、或多個關聯資料表，2 GB 可能在 1-2 年內就會用滿。

4. 缺乏進階功能

• 限制：Basic 不支援 Point-in-Time Restore (PITR) 較長的天數（僅 7 天），且不支援異地備份。
• 情境：如果有人不小心刪錯資料，你只能回推到過去 7 天內。

針對「校務建言系統」的架構建議

既然你已經規劃將附件存放在 Blob Storage，這大大減輕了資料庫的壓力。以下是針對你的專案建議的部署策略：

策略 A：初期省錢法 (開發階段)

• 使用 Basic (5 DTU)：在開發與內部測試（10 人以內）時完全足夠。
• 優點：成本極低，適合慢慢磨功能。

策略 B：上線初期/正式運行 (彈性調整)

• 升級至 Standard (S0 或 S1)：
  • S0 (10 DTU)：約 $15 USD/月，支援 60 個併發連線，容量可達 250GB。
  • S1 (20 DTU)：約 $30 USD/月，效能明顯提升，適合應對一般校園流量。

策略 C：極致省錢法 (使用 Serverless)

如果你不希望固定每個月付 $15~$30 USD，可以考慮從 DTU 模式切換到 vCore – Serverless：

• 運作邏輯：建言系統通常「晚上沒人用」或「假日時段冷門」。Serverless 可以在沒人點擊網頁時自動暫停。
• 費用：可能比 Standard 更便宜，卻能提供比 Basic 更強大的瞬間處理能力。

總結建議

你的校務系統**「平時」用 Basic 是可以的，但「宣傳推廣期」**一定會卡頓。

我的實務建議：

先用 Basic 開發。等系統準備正式發布給學生使用的那一天，手動在 Azure Portal 將級別調整至 Standard S1（調整過程資料庫不會停機）。等宣傳熱潮過了，再降回 Basic 或 S0 節省開支。

---

如何在程式碼中（例如 C# 或 Python）實作「上傳附件到 Blob 並將 URL 寫回 SQL」的最佳實踐

這是一個非常標準且高效的雲端開發模式：SQL 存放結構化資料（後設資料），Blob Storage 存放非結構化的大檔案（圖片、PDF、文件）。

這種做法能讓資料庫保持輕量，避免 DTU - Basic 的空間迅速被填滿。以下是實作「校務建言系統」附件處理的最佳實踐與範例：

1. 資料庫資料表設計 (SQL Side)

不要在 SQL 中存檔案本身（Blob 類型），而是存檔案的 URL 和 唯一識別碼 (GUID)。

SQL

CREATE TABLE Suggestions (
    Id INT PRIMARY KEY IDENTITY(1,1),
    StudentId NVARCHAR(50),
    Content NVARCHAR(MAX),
    CreatedAt DATETIME DEFAULT GETDATE()
);

CREATE TABLE Attachments (
    Id INT PRIMARY KEY IDENTITY(1,1),
    SuggestionId INT, -- 關聯到建言
    FileName NVARCHAR(255),
    BlobUrl NVARCHAR(2048), -- 儲存 Blob 的完整路徑
    BlobName GUID, -- 建議用 GUID 命名檔案以防重複
    FOREIGN KEY (SuggestionId) REFERENCES Suggestions(Id)
);

2. 檔案上傳邏輯 (Workflow)

在開發時，建議遵循以下流程以確保效能：

1. 前端上傳：使用者送出建言與檔案。
2. 後端處理：
   • 產生一個唯一的檔名（例如 guid.jpg）。
   • 使用 Azure Storage SDK 將檔案上傳至 Blob Storage。
   • 取得該檔案的 永久連結 (URL) 或路徑。
3. 寫入資料庫：將建言文字與該 URL 同步寫入 SQL Database。

3. C# 程式碼範例 (使用 Azure.Storage.Blobs)

這是最常見的實作方式，簡潔且安全：

C#

// 1. 初始化 Blob 客戶端
BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);
BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient("school-attachments");

// 2. 上傳檔案
string blobName = Guid.NewGuid().ToString() + Path.GetExtension(file.FileName);
BlobClient blobClient = containerClient.GetBlobClient(blobName);

using (var stream = file.OpenReadStream())
{
    await blobClient.UploadAsync(stream, true);
}

// 3. 取得 URL 並存入 SQL
string fileUrl = blobClient.Uri.ToString();
// 接下來使用 ADO.NET 或 Entity Framework 將 fileUrl 存入 Attachments 表

4. 進階安全性建議：SAS Token

由於校務系統可能涉及隱私（例如建言者不想讓別人看到他的附件），你不應該把 Blob Container 設為「公開讀取」。

• 做法：將 Container 設為 Private (私用)。
• 讀取方式：當使用者要查看附件時，後端產生一個 暫時性的簽署 URL (Shared Access Signature, SAS)。
• 優點：這個連結會在 10 分鐘或 1 小時後失效，即使連結外流，別人也無法下載。

5. 為什麼這樣做對 Basic 級別最有利？

• 節省 DTU 消耗：資料庫不需要處理大數據流（I/O），只需處理簡短的文字字串。
• 節省空間：SQL Basic 的 2GB 限制可以撐非常久，因為幾萬筆 URL 頂多才幾十 MB。
• 成本優勢：Blob Storage 每 GB 的價格（約 $0.02 USD）遠低於 SQL Database 空間。

使用 Python 實作「上傳檔案至 Blob 並將 URL 寫入 SQL」是非常直覺的。我們通常會使用 azure-storage-blob 套件處理檔案，並使用 pyodbc 或 SQLAlchemy 處理資料庫。

以下是一個完整的邏輯範例：

1. 安裝必要套件

在你的開發環境中執行：

Bash

pip install azure-storage-blob pyodbc

2. Python 實作程式碼

這個範例展示了如何接收一個檔案、上傳到 Azure，最後把資料存進 SQL Database。

Python

import os
import uuid
from azure.storage.blob import BlobServiceClient
import pyodbc

# --- 1. 設定連線資訊 ---
# Azure Blob Storage 連線字串
AZURE_STORAGE_CONNECTION_STRING = "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;"
CONTAINER_NAME = "school-attachments"

# Azure SQL 連線資訊 (注意：Basic 級別請確保防火牆已開放 IP)
SQL_CONNECTION_STRING = (
    "Driver={ODBC Driver 18 for SQL Server};"
    "Server=tcp:your-server.database.windows.net,1433;"
    "Database=your-db;"
    "Uid=your-username;Pwd=your-password;"
    "Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;"
)

def upload_suggestion_with_attachment(student_id, content, file_path):
    try:
        # --- 2. 上傳檔案到 Blob Storage ---
        blob_service_client = BlobServiceClient.from_connection_string(AZURE_STORAGE_CONNECTION_STRING)
        container_client = blob_service_client.get_container_client(CONTAINER_NAME)
        
        # 產生唯一檔名避免重複 (例如: 550e8400-e29b.pdf)
        file_extension = os.path.splitext(file_path)[1]
        unique_blob_name = f"{uuid.uuid4()}{file_extension}"
        
        blob_client = container_client.get_blob_client(unique_blob_name)
        
        print(f"正在上傳檔案: {unique_blob_name}...")
        with open(file_path, "rb") as data:
            blob_client.upload_blob(data)
        
        # 取得上傳後的 URL
        blob_url = blob_client.url
        print(f"上傳成功！URL: {blob_url}")

        # --- 3. 將資料寫入 SQL Database ---
        conn = pyodbc.connect(SQL_CONNECTION_STRING)
        cursor = conn.cursor()

        # 插入建言並取得 ID (SQL Server 語法)
        cursor.execute(
            "INSERT INTO Suggestions (StudentId, Content) OUTPUT INSERTED.Id VALUES (?, ?)",
            (student_id, content)
        )
        suggestion_id = cursor.fetchone()[0]

        # 插入附件資訊
        cursor.execute(
            "INSERT INTO Attachments (SuggestionId, FileName, BlobUrl, BlobName) VALUES (?, ?, ?, ?)",
            (suggestion_id, os.path.basename(file_path), blob_url, unique_blob_name)
        )

        conn.commit()
        print("資料庫寫入完成！")

    except Exception as ex:
        print(f"發生錯誤: {ex}")
    finally:
        if 'conn' in locals():
            conn.close()

# 測試執行
upload_suggestion_with_attachment("S123456", "飲水機過濾網該換了", "report.pdf")

3. 進階架構優化（省錢與安全）

在實際開發校務系統時，還有兩點建議：

A. 非同步上傳 (Async)

如果你的系統是使用 FastAPI 或 Django，建議使用 azure-storage-blob 的非同步版本 (BlobServiceClient from azure.storage.blob.aio)。這樣當多個學生同時上傳大檔案時，不會卡住整個伺服器的執行緒。

B. 使用受控識別 (Managed Identity) —— 強烈建議

與其在程式碼中寫死資料庫密碼（Uid/Pwd），你可以啟用 Web App 的 Managed Identity。

• 好處：不需要在設定檔存密碼。
• 安全性：即使程式碼外流，別人也拿不到資料庫權限。
• 適用：這在跨資源群組存取時非常方便且安全。

4. 針對 DTU – Basic 的特別提醒

在使用 Python 連線時，請務必在 pyodbc 的連線字串中加入 Connection Timeout=30。

因為 Basic 級別的資源較少，有時候冷啟動或排隊會稍微慢一點，適度增加超時時間可以減少連線失敗的機率。

透過 sqlcmd 匯入資料庫 (不經過 SSMS):

sqlcmd -S localhost -d %db_name% -E -i %output_file%

這個也會遇到很多奇奇怪怪的問題, 明明在 SSMS 執行正常的 table, 在 sqlcmd 會遇到重覆插入 PK 值.

最佳解法是透過下列的python script 進行 export, 這是整合了「逐行讀取」、「自動切分 1000 筆」、「停用約束」以及修正後語法的完整版本：

import re
import pyodbc
import argparse
import sys

def parse_value(val_str):
    """Parse a single SQL value string and return a Python value."""
    val_str = val_str.strip()
    if val_str.upper() == 'NULL':
        return None
    if (val_str.startswith("'") and val_str.endswith("'")):
        # Remove surrounding quotes
        inner = val_str[1:-1]
        # Unescape MySQL-style escape sequences
        result = []
        i = 0
        while i < len(inner):
            if inner[i] == '\\' and i + 1 < len(inner):
                next_char = inner[i + 1]
                if next_char == "'":
                    result.append("'")
                elif next_char == "\\":
                    result.append("\\")
                elif next_char == "n":
                    result.append("\n")
                elif next_char == "r":
                    result.append("\r")
                elif next_char == "t":
                    result.append("\t")
                elif next_char == "0":
                    result.append("\0")
                elif next_char == "%":
                    result.append("%")
                elif next_char == "_":
                    result.append("_")
                else:
                    result.append(next_char)
                i += 2
            elif inner[i] == "'" and i + 1 < len(inner) and inner[i + 1] == "'":
                # SQL-style escaped quote
                result.append("'")
                i += 2
            else:
                result.append(inner[i])
                i += 1
        return "".join(result)
    # Try numeric
    try:
        if '.' in val_str:
            return float(val_str)
        return int(val_str)
    except ValueError:
        return val_str

def split_row_values(row_str):
    """Split a single row '(val1, val2, ...)' into individual values."""
    # Remove outer parentheses
    inner = row_str.strip()
    if inner.startswith('('):
        inner = inner[1:]
    if inner.endswith(')'):
        inner = inner[:-1]
    
    values = []
    current = []
    in_string = False
    i = 0
    
    while i < len(inner):
        char = inner[i]
        
        if in_string:
            if char == '\\' and i + 1 < len(inner):
                current.append(char)
                current.append(inner[i + 1])
                i += 2
                continue
            elif char == "'":
                # Check for escaped quote ''
                if i + 1 < len(inner) and inner[i + 1] == "'":
                    current.append(char)
                    current.append(inner[i + 1])
                    i += 2
                    continue
                else:
                    in_string = False
                    current.append(char)
            else:
                current.append(char)
        else:
            if char == "'":
                in_string = True
                current.append(char)
            elif char == ',':
                values.append("".join(current).strip())
                current = []
            else:
                current.append(char)
        i += 1
    
    if current:
        values.append("".join(current).strip())
    
    return values

def split_values_robust(values_str):
    """Split VALUES (...),(...),... into individual row strings."""
    rows = []
    buffer = []
    paren_depth = 0
    in_string = False
    i = 0
    length = len(values_str)
    
    while i < length:
        char = values_str[i]
        
        if in_string:
            if char == "\\" and i + 1 < length:
                buffer.append(char)
                buffer.append(values_str[i + 1])
                i += 2
                continue
            elif char == "'":
                # Check for '' escape
                if i + 1 < length and values_str[i + 1] == "'":
                    buffer.append(char)
                    buffer.append(values_str[i + 1])
                    i += 2
                    continue
                in_string = False
                buffer.append(char)
            else:
                buffer.append(char)
        else:
            if char == "'":
                in_string = True
                buffer.append(char)
            elif char == "(":
                paren_depth += 1
                buffer.append(char)
            elif char == ")":
                paren_depth -= 1
                buffer.append(char)
                if paren_depth == 0:
                    rows.append("".join(buffer).strip())
                    buffer = []
            elif char == "," and paren_depth == 0:
                pass
            else:
                if paren_depth > 0:
                    buffer.append(char)
        i += 1
    return rows

def run_import(input_file):
    # 資料庫連線配置
    conn_config = {
        "DRIVER": "{ODBC Driver 18 for SQL Server}",
        "SERVER": "127.0.0.1",
        "DATABASE": "你的資料庫名稱",
        "UID": "帳號",
        "PWD": "密碼",
        "Encrypt": "yes",
        "TrustServerCertificate": "yes"
    }

    conn_str = ";".join([f"{k}={v}" for k, v in conn_config.items()])

    try:
        conn = pyodbc.connect(conn_str, autocommit=False)
        cursor = conn.cursor()
        print(f"檔案讀取中: {input_file}")
    except Exception as e:
        print(f"連線失敗: {e}")
        return

    try:
        with open(input_file, 'r', encoding='utf-8') as f:
            sql_content = f.read()
    except Exception as e:
        print(f"讀檔失敗: {e}")
        return

    # Handle INSERT INTO with parameterized queries
    insert_pattern = re.compile(
        r"INSERT INTO\s+`?([\w_]+)`?\s*(?:\((.*?)\))?\s*VALUES\s*(.+?);",
        re.S | re.I
    )

    truncated_tables = set()  # Track tables already truncated
    table_stats = {}  # Track cumulative success/error counts per table

    for match in insert_pattern.finditer(sql_content):
        table_name = match.group(1)
        cols_raw = match.group(2) if match.group(2) else ""
        raw_values = match.group(3)

        # Build column clause
        if cols_raw:
            col_names = [c.strip().replace('`', '') for c in cols_raw.split(',')]
            columns_clause = "([" + "],[".join(col_names) + "])"
        else:
            # No column list in SQL dump — fetch from MSSQL metadata
            # This is required when IDENTITY_INSERT is ON
            try:
                cursor.execute("""
                    SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS
                    WHERE TABLE_NAME = ?
                    ORDER BY ORDINAL_POSITION
                """, table_name)
                db_cols = [row[0] for row in cursor.fetchall()]
                if db_cols:
                    columns_clause = "([" + "],[".join(db_cols) + "])"
                else:
                    columns_clause = ""
            except:
                columns_clause = ""

        print(f"正在處理: {table_name}")

        # Truncate table before inserting (only once per table)
        if table_name not in truncated_tables:
            try:
                cursor.execute(f"TRUNCATE TABLE [{table_name}]")
                conn.commit()
                print(f"  已清空資料表: {table_name}")
            except Exception as e:
                conn.rollback()
                # TRUNCATE fails if there are foreign key constraints, fallback to DELETE
                try:
                    cursor.execute(f"DELETE FROM [{table_name}]")
                    conn.commit()
                    print(f"  已清空資料表 (DELETE): {table_name}")
                except Exception as e2:
                    conn.rollback()
                    print(f"  清空資料表失敗: {table_name}: {e2}")
            truncated_tables.add(table_name)

        all_rows = split_values_robust(raw_values)
        print(f"  共 {len(all_rows)} 筆資料")

        success_count = 0
        error_count = 0

        # Check if table has IDENTITY column, if so enable IDENTITY_INSERT
        has_identity = False
        try:
            cursor.execute(f"""
                SELECT COUNT(*) FROM sys.identity_columns 
                WHERE OBJECT_NAME(object_id) = ?
            """, table_name)
            row = cursor.fetchone()
            if row and row[0] > 0:
                has_identity = True
        except:
            pass

        if has_identity:
            try:
                cursor.execute(f"SET IDENTITY_INSERT [{table_name}] ON")
            except Exception as e:
                print(f"  無法開啟 IDENTITY_INSERT: {e}")

        for idx, row_str in enumerate(all_rows):
            raw_vals = split_row_values(row_str)
            parsed_vals = [parse_value(v) for v in raw_vals]
            
            placeholders = ",".join(["?" for _ in parsed_vals])
            sql = f"INSERT INTO [{table_name}] {columns_clause} VALUES ({placeholders})"
            
            try:
                cursor.execute(sql, parsed_vals)
                conn.commit()
                success_count += 1
            except Exception as e:
                conn.rollback()
                error_count += 1
                if error_count <= 3:
                    print(f"  跳過錯誤列 {idx}: {e}")
                    # Print the values for debugging
                    preview_vals = [str(v)[:50] if v is not None else 'NULL' for v in parsed_vals]
                    print(f"  值預覽: {preview_vals}")
                elif error_count == 4:
                    print(f"  (後續錯誤將不再顯示...)")

        if has_identity:
            try:
                cursor.execute(f"SET IDENTITY_INSERT [{table_name}] OFF")
            except:
                pass

        # Accumulate stats per table
        if table_name not in table_stats:
            table_stats[table_name] = {"success": 0, "error": 0}
        table_stats[table_name]["success"] += success_count
        table_stats[table_name]["error"] += error_count
        print(f"  本批: 成功 {success_count} 筆, 失敗 {error_count} 筆")

    # Print summary for tables with multiple INSERT batches
    print("\n=== 匯入摘要 ===")
    for tbl, stats in table_stats.items():
        print(f"  {tbl}: 成功 {stats['success']} 筆, 失敗 {stats['error']} 筆")

    cursor.close()
    conn.close()
    print("全部完成。")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="MariaDB To MSSQL Migration Tool")
    parser.add_argument("input", help="Path to the .sql dump file")
    args = parser.parse_args()
    
    run_import(args.input)

如果執行過程中遇到記憶體不足的問題，通常是因為 split_values 處理了單一極其巨大的 INSERT 字串。若發生此情況，請告訴我，我們可以改用生成器（Generator）模式來進一步優化字串解析。

上面這個版本針對一般情況是可以使用，針對特定的資料庫欄位類型（例如 Blob 或特殊的日期格式）則需要再進一步的轉換處理。

執行結果:

要在 Python 中將資料寫入 MSSQL，最常見且穩定的組合是使用 pyodbc 套件配合微軟官方提供的 ODBC Driver。安裝檔下載:

下載適用於 SQL Server 的 ODBC 驅動程式
https://learn.microsoft.com/zh-tw/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver17

需安裝的組件

系統層級需要安裝 Microsoft ODBC Driver for SQL Server。這是微軟提供的驅動程式，讓作業系統能夠與 SQL Server 通訊。建議安裝最新的版本（如 Driver 18 或 17）。

Python 環境則需要安裝 pyodbc 函式庫。你可以透過 pip install pyodbc 指令完成安裝。如果你的專案較具規模，通常也會搭配 sqlalchemy 配合 pandas 來處理大數據量，安裝指令為 pip install sqlalchemy pandas。

實作範例

以下是使用 pyodbc 進行單筆資料插入的標準寫法：

Python

import pyodbc

# 設定連線資訊
conn_config = {
    "DRIVER": "{ODBC Driver 18 for SQL Server}",
    "SERVER": "127.0.0.1", # 如果是本機也可以用 localhost 或 (local)
    "DATABASE": "你的資料庫名稱",
    "UID": "帳號",
    "PWD": "密碼",
    "Encrypt": "yes",
    "TrustServerCertificate": "yes"
}

conn_str = ";".join([f"{k}={v}" for k, v in conn_config.items()])

def sync_database():
    conn = None
    try:
        # 建立連線
        conn = pyodbc.connect(conn_str)
        cursor = conn.cursor()

        table_name = "UserLogs"
        
        # 1. 檢查資料表是否存在
        check_sql = "SELECT 1 FROM sys.objects WHERE object_id = OBJECT_ID(?) AND type = 'U'"
        cursor.execute(check_sql, table_name)
        
        if not cursor.fetchone():
            print(f"資料表 {table_name} 不存在，正在建立...")
            # 2. 建立資料表
            create_sql = f"""
            CREATE TABLE {table_name} (
                ID INT IDENTITY(1,1) PRIMARY KEY,
                UserName NVARCHAR(50),
                ActionTime DATETIME DEFAULT GETDATE(),
                Status NVARCHAR(20)
            )
            """
            cursor.execute(create_sql)
            conn.commit()
            print("資料表建立成功")

        # 3. 執行資料插入
        insert_sql = f"INSERT INTO {table_name} (UserName, Status) VALUES (?, ?)"
        cursor.execute(insert_sql, ("Max", "Active"))
        conn.commit()
        print("資料插入成功")

        # 4. 刪除資料表 (Drop Table)
        print(f"正在刪除資料表 {table_name}...")
        drop_sql = f"DROP TABLE {table_name}"
        cursor.execute(drop_sql)
        conn.commit()
        print("資料表已刪除")

    except pyodbc.Error as e:
        print(f"資料庫操作失敗: {e}")
        if conn:
            conn.rollback()
    finally:
        if conn:
            cursor.close()
            conn.close()

if __name__ == "__main__":
    sync_database()

注意事項

在連線字串中，如果你是連線到本機測試環境且沒有設定 SSL 憑證，務必加上 TrustServerCertificate=yes 參數，否則常會因為加密安全性檢查而導致連線失敗。另外，對於大量資料的寫入，建議使用 cursor.fast_executemany = True 或者是 pandas 的 to_sql 方法，這能顯著提升寫入效能。

在 conn_config 中明確加上了 Encrypt: yes。這是因為 ODBC Driver 18 預設要求加密連線。配合 TrustServerCertificate: yes，可以跳過 SSL 憑證的有效性檢查，通常能解決無法開啟具名管道或連線逾時的問題。

如果你的 SQL Server 是 Express 版本，SERVER 欄位可能需要寫成 127.0.0.1\SQLEXPRESS 這種格式，請根據你的實例名稱進行調整。

雖然您的電腦可以連線到 SQL Server，但伺服器使用的 SSL/TLS 憑證已經過期。

因為加密憑證失效，為了安全性，系統自動阻斷了登入程序。您可以透過以下幾種方式解決：

方案一：快速跳過驗證（用戶端暫時解決方案）

如果您需要立即連線且處於安全的內部網路，可以調整 SQL Server Management Studio (SSMS) 的設定，忽略憑證過期問題。

1. 在「連線至伺服器」視窗（輸入帳號密碼的地方），點擊右下角的 「選項 (O) >>」。
2. 切換到 「連線屬性」 頁籤。
3. 勾選 「信任伺服器憑證」(Trust server certificate)。
4. 再次嘗試 「連線」。

方案二：檢查系統時間

憑證效期是根據時間計算的。如果您的電腦或是伺服器的 系統日期/時間不正確（例如年份跳掉了），也會導致憑證被判定為過期。

• 操作： 請確認您的電腦與資料庫伺服器的時間都已經同步到目前的正確時間。

方案三：更換憑證（伺服器端永久解決方案）

如果您是該伺服器的管理員，應更新伺服器上的憑證，以確保所有使用者都能安全連線。

1. 開啟工具： 開啟「SQL Server 組態管理員」(SQL Server Configuration Manager)。
2. 尋找協定： 導航至「SQL Server 網路組態」 > 「[您的實例名稱] 的協定」。
3. 檢查憑證： 右鍵點擊「內容」，在「憑證」頁籤中可以看到目前過期的憑證資訊。
4. 更換： 申請新的憑證（或產生新的自我簽署憑證）並在此處重新選取。
5. 重啟服務： 更改憑證後，必須重啟 SQL Server 服務才會生效。

為什麼以前沒問題，現在突然出現？

這通常有兩個原因：

1. 憑證真的剛好在最近到期了。
2. 您最近更新了 SSMS 19.x 或更高版本。新版本預設將「加密」設為強制開啟，這會導致原本不嚴謹的連線環境（使用過期或自我簽署憑證）開始報錯。