Mac 上使用 python 工具 uv

uv 是一個新的 Python 工具鏈，透過 效能優化、功能整合與使用者友善設計，簡化了 Python 專案的開發、依賴管理和發布流程。

MacOS 安裝 uv

最簡單的方式是使用 homebrew 安裝 uv

brew install uv

透過 uv 特定版本的 python

安裝好後可以查看已安裝的 python 版本

# 查看已安裝的 python 版本
uv python list

cpython-3.14.0a7-macos-aarch64-none                 <download available>
cpython-3.14.0a7+freethreaded-macos-aarch64-none    <download available>
cpython-3.13.3-macos-aarch64-none                   <download available>
cpython-3.13.3+freethreaded-macos-aarch64-none      <download available>
cpython-3.13.2-macos-aarch64-none                   /opt/homebrew/bin/python3.13 -> ../Cellar/python@3.13/3.13.2/bin/python3.13
cpython-3.13.2-macos-aarch64-none                   /opt/homebrew/bin/python3 -> ../Cellar/python@3.13/3.13.2/bin/python3
cpython-3.12.10-macos-aarch64-none                  <download available>
cpython-3.12.7-macos-aarch64-none                   /opt/homebrew/bin/python3.12 -> ../Cellar/python@3.12/3.12.7_1/bin/python3.12
cpython-3.11.12-macos-aarch64-none                  .local/share/uv/python/cpython-3.11.12-macos-aarch64-none/bin/python3.11
cpython-3.10.17-macos-aarch64-none                  <download available>
cpython-3.10.15-macos-aarch64-none                  /opt/homebrew/bin/python3.10 -> ../Cellar/python@3.10/3.10.15/bin/python3.10
cpython-3.9.22-macos-aarch64-none                   <download available>
cpython-3.9.6-macos-aarch64-none                    /usr/bin/python3

安裝特定版本的 python

uv python install 3.11

透過 uv 建立專案有兩種方式: - 和原有的 pip 和 venv 相容的方式 - 直接使用 uv 管理

搭配 pip 和 venv 建立專案

# 指定 python 版本，建立專案語法
uv venv --python=<version> <env-name>
# 範例
uv venv --python=3.12 .venv

這種方式的缺點是沒有記錄 python 版本，但實際上在 .venv/pyvenv.cfg 可以查看相關設定，但沒有記錄到版控。

# 安裝套件
uv pip install requests

直接使用 uv 管理

# 初始化專案
uv init --python 3.11

會直接建立專案的 git 設定，同時建立專案設定檔 pyproject.toml。

# 加入套件
uv add requests

加入任一套件後會自動建立 .venv 資料夾，並把虛擬環境建立起來。同時把安裝的套件記錄在 pyproject.toml。 pyproject.toml 的角色類似 nodejs 專案的 package.json。其他常用的指令如下：

# 查看 uv 用法
uv -h

# 移除套件
uv remove <套件>
uv remove requests

# 執行指令或程式
uv run <程式或指令>
uv run main.py

# 更新特定套件
uv lock --upgrade-package requests

# 更新所有套件
uv lock --upgrade

nginx 反向代理 fastapi 和 ollama 服務

uvicorn 和 fastapi

使用 Uvicorn 要注意的大概就是 proxy_set_header 那邊的設定。其他 https 的部份，請使用 Certbot 幫忙搞定。

server {
    server_name domain.shinder.cc; # managed by Certbot

    add_header Accept-Ranges bytes;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
        proxy_cache off;
    }

    listen [::]:443 ssl ipv6only=on; # managed by Certbot
    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/domain.shinder.cc/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/domain.shinder.cc/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}

server {
    if ($host = domain.shinder.cc) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80 ;
    listen [::]:80 ;
    server_name domain.shinder.cc;
    return 404; # managed by Certbot
}

ollama

一般為了安全性 ollama 服務是不對外的。在此的情境是，想讓遠端使用資源，但限定 IP。對外開放的通訊埠為 11435。

server {
    server_name _;

    add_header Accept-Ranges bytes;
    location / {
        proxy_pass http://127.0.0.1:11434;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
        proxy_cache off;

        allow   192.168.1.100;  # 允許 192.168.1.100 訪問
        deny    all;             # 拒絕所有其他 IP 訪問
    }

    listen [::]:11435;
    listen 11435;
}

Ubuntu 重新開機後以 pm2 重啟行程

一般建議使用 systemd 來設定，這裡記錄一下 pm2 的作法。

# 1. 啟動設定，pm2 會依使用的系統，寫入啟動的 script (例如 systemd)
# 這部份可以免除複雜的設定，交給 pm2 處理就好
pm2 startup

# 2. 以 pm2 啟動你要執行的行程，通常是 Nodejs 應用
pm2 start index.js --name mfee62_3000

# 3. 儲存設定
pm2 save
# pm2 會依據目前記憶體內正在執行的行程，儲存一個記錄檔以利重開機後重啟這些行程

使用 homebrew 安裝 apache2 和 php 環境

XAMPP 的 mac 版本現在都比較老舊，而且在 macOS 15 有無法啟動 apache 的問題。 為了教學需求，在此記錄 mac 的 php 環境的建立方式。假設 homebrew 的環境已經安裝完成。 如果要使用 ubuntu vm 可以參考上一篇 https://qops.blogspot.com/2025/03/orbstack-ubuntu-224-php-56-apache2.html 的作法。

安裝 apache2

# 先查看是否已安裝
brew info apache2
# 前幾行若出現 Not installed 表示沒有安裝，後面也有設定的說明

# 安裝
brew install apache2
# 安裝後，注意預先的設定
# -- DocumentRoot is /opt/homebrew/var/www
# -- 主設定檔位置 /opt/homebrew/etc/httpd/httpd.conf
# -- ssl 設定檔位置 /opt/homebrew/etc/httpd/extra/httpd-ssl.conf
# -- 預設的 ports 為 8080 和 8443

# 啟動服務
brew services start httpd
# 在瀏覽器上查看 http://localhost:8080

# 重新啟動服務
brew services restart httpd

# 停止服務
brew services stop httpd

安裝 php

這裡是以 php 8.3 的版本為例說明，當然你可以自行決定要安裝的版本。

# 先查看要安裝的版本資訊
brew info php@8.3

# 安裝
brew install php@8.3

# 在 apache 的設定檔，放入下式
LoadModule php_module /opt/homebrew/opt/php@8.3/lib/httpd/modules/libphp.so

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

# 設定索引檔
DirectoryIndex index.php index.html

PHP 的設定檔位於 /opt/homebrew/etc/php/8.3/ 裡面。

# 若要使用 php 指令，可以將下兩行放入用戶設定檔 (.zshrc) 裡 
export PATH="/opt/homebrew/opt/php@8.3/bin:$PATH"
export PATH="/opt/homebrew/opt/php@8.3/sbin:$PATH"

在根目錄 /opt/homebrew/var/www 寫一支 phpinfo() 檔測試看看。

mysql 8.0

# 先查看要安裝的版本資訊
brew info mysql@8.0

# 安裝
brew install mysql@8.0

# 啟動服務
brew services start mysql@8.0

OrbStack 安裝 Ubuntu 22.4, php 5.6 及 apache2

某個專案還在老舊的 php 5.6 環境，macOS 15 Sequoia 目前已無法正常執行 XAMPP。在不小心升級 macOS 後，測試 php 5.6 程式是讓人困擾的問題。

原本想要使用 OrbStack 的 docker containers 功能，然而 container 需要不少設定，反而是一種麻煩的做法。後來還是以 VM 的方式來處理。OrbStack 的安裝就不贅述。

安裝 ubuntu vm

# *** 安裝 ubuntu vm ***
# orb create --help
# orb create [flags] DISTRO[:VERSION] [MACHINE_NAME]
orb create ubuntu:jammy  # 預設的 machine name 為 ubuntu

# *** 從 mac ssh 連線 vm ***
# ssh [用戶名]@[虛擬主機名]@orb
ssh root@ubuntu@orb

# *** 使用 vm 的 domain ***
# ping [虛擬主機名].orb.local
ping ubuntu.orb.local
# mac host 的 ip 可以直接使用區域網路 ip

在 vm 中可以透過 /mnt/mac 路徑找到 mac 的對應檔案。

安裝 php 5.6

以 ssh 登入 vm 後，依下列步驟安裝 php 5.6

# *** 1. 更新系統 repo 資料
apt update

# *** 2. 安裝 software-properties-common 以管理 PPA (Personal Package Archives)
apt install software-properties-common

# *** 3. php 5.6 已經不是官方維護的版本，需依賴 PPA
add-apt-repository ppa:ondrej/php

# *** 4. 再更新系統 repo 資料一次
apt update

# *** 5. 安裝 php 5.6
apt install php5.6

# *** 6. 安裝 php 常用套件
apt install php5.6-mysql php5.6-curl php5.6-json php5.6-cgi php5.6-xml php5.6-mbstring php5.6-gd

# *** 7. 確認 php 版本
php -v

# *** 8. 啟用 apache2 模組
# 在安裝 apache2 之後才可以執行
# a2dismod php8.3 # 若有需要先關閉新模組
a2enmod php5.6

安裝 apache2

apt install apache2

# 啟用 rewrite module
a2enmod rewrite

# /etc/apache2/mods-enabled 裡啟用的模組參考
access_compat.load -> ../mods-available/access_compat.load
alias.conf -> ../mods-available/alias.conf
alias.load -> ../mods-available/alias.load
auth_basic.load -> ../mods-available/auth_basic.load
authn_core.load -> ../mods-available/authn_core.load
authn_file.load -> ../mods-available/authn_file.load
authz_core.load -> ../mods-available/authz_core.load
authz_host.load -> ../mods-available/authz_host.load
authz_user.load -> ../mods-available/authz_user.load
autoindex.conf -> ../mods-available/autoindex.conf
autoindex.load -> ../mods-available/autoindex.load
cache.load -> ../mods-available/cache.load
cache_disk.conf -> ../mods-available/cache_disk.conf
cache_disk.load -> ../mods-available/cache_disk.load
deflate.conf -> ../mods-available/deflate.conf
deflate.load -> ../mods-available/deflate.load
dir.conf -> ../mods-available/dir.conf
dir.load -> ../mods-available/dir.load
env.load -> ../mods-available/env.load
expires.load -> ../mods-available/expires.load
file_cache.load -> ../mods-available/file_cache.load
filter.load -> ../mods-available/filter.load
headers.load -> ../mods-available/headers.load
mime.conf -> ../mods-available/mime.conf
mime.load -> ../mods-available/mime.load
mpm_prefork.conf -> ../mods-available/mpm_prefork.conf
mpm_prefork.load -> ../mods-available/mpm_prefork.load
negotiation.conf -> ../mods-available/negotiation.conf
negotiation.load -> ../mods-available/negotiation.load
php5.6.conf -> ../mods-available/php5.6.conf
php5.6.load -> ../mods-available/php5.6.load
reqtimeout.conf -> ../mods-available/reqtimeout.conf
reqtimeout.load -> ../mods-available/reqtimeout.load
rewrite.load -> ../mods-available/rewrite.load
setenvif.conf -> ../mods-available/setenvif.conf
setenvif.load -> ../mods-available/setenvif.load
socache_shmcb.load -> ../mods-available/socache_shmcb.load
ssl.conf -> ../mods-available/ssl.conf
ssl.load -> ../mods-available/ssl.load
status.conf -> ../mods-available/status.conf
status.load -> ../mods-available/status.load

安裝 Mariadb 10

# *** 1. 更新套件資訊
apt update

# *** 2. 查看可以安裝的子版本
apt-cache policy mariadb-server

# *** 3. 安裝
apt install mariadb-server

# 以 mysql client 使用 root 登入
mysql -uroot

# 變更 root 密碼
ALTER USER 'root'@'localhost' IDENTIFIED BY '你的密碼';

# 建立管理用戶給 phpmyadmin 使用
CREATE USER 'pmauser'@'localhost' IDENTIFIED BY 'pmauser';
GRANT ALL PRIVILEGES ON *.* TO 'pmauser'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

# 查看使用者
SELECT User, Host FROM mysql.user;