diff --git a/docs/en/friendly/index.md b/docs/en/friendly/index.md index 2dca06d6..72c5e89b 100644 --- a/docs/en/friendly/index.md +++ b/docs/en/friendly/index.md @@ -18,6 +18,14 @@ const members = [ { icon: 'rss', link: 'http://nhui.top/' }, ] }, + { + avatar: '/xiangcai.png', + name: '香菜', + title: '香菜的博客', + links: [ + { icon: 'rss', link: 'https://mdzz.pro/' }, + ] + }, ] diff --git a/docs/en/tips/devops/certbot.md b/docs/en/tips/devops/certbot.md new file mode 100644 index 00000000..747b65e2 --- /dev/null +++ b/docs/en/tips/devops/certbot.md @@ -0,0 +1,58 @@ +--- +title: Certbot Automatic SSL Certificate Acquisition +author: Lee +--- + +## Installation + +```bash +sudo apt update +sudo apt install certbot +``` + +If using nginx, also install the plugin: + +```bash +sudo apt install certbot python3-certbot-nginx +``` + +If applying for a wildcard certificate using DNS, install the plugin: + +```bash +sudo apt install python3-certbot-dns-cloudflare +``` + +## Request Certificate + +No web server used: + +```bash +sudo certbot certonly -d yourdomain +``` + +### Using nginx + +```bash +sudo certbot --nginx -d yourdomain +``` + +### Using DNS + +Taking Cloudflare as an example: + +1. Cloudflare management account > Account API Tokens > API Token Templates > Edit Zone DNS +2. Install plugin `sudo apt install python3-certbot-dns-cloudflare` +3. Create the file `etc/letsencrypt/cloudflare.ini` and place the parameter inside: `dns_cloudflare_api_token = yourtoken` +4. Run `sudo certbot certonly -d yourdomain` and choose DNS authentication when prompted. + +> It is not recommended to remove `cloudflare.ini` after applying. Certbot needs this file for automatic renewal. + +## Using the Certificate + +After configuration, the terminal will display the paths for the certificate and private key, which can be set in `ssl_certificate` and `ssl_certificate_key` for use. + +For other configuration parts, refer to [nginx reverse proxy basics](./nginx.md) + +## Note + +Certbot will automatically add relevant configurations to nginx's `etc/nginx/sites-available/default` file. This may conflict with your site configuration file. You can comment out lines marked with `# managed by Certbot`. diff --git a/docs/en/tips/devops/hass.md b/docs/en/tips/devops/hass.md new file mode 100644 index 00000000..6c2261be --- /dev/null +++ b/docs/en/tips/devops/hass.md @@ -0,0 +1,121 @@ +--- +title: Home Assistant Reverse Proxy + Access Whitelist +author: Lee +--- + +## Installation + +Refer to the official documentation: + +I installed using Docker Compose and recommend this method.[Official documentation](https://www.home-assistant.io/installation/linux#docker-compose) + +## Reverse Proxy + +Home Assistant's security policy disables reverse proxy by default. Modify `configuration.yaml`. + +```yaml +# configuration.yaml +http: + # It is recommended to configure SSL only in nginx; there is no need for two layers of SSL for internal reverse proxies + #ssl_certificate: [.crt file] + #ssl_key: [.key file] + use_x_forwarded_for: true + trusted_proxies: #Reverse proxy whitelist. If not this IP, change it accordingly. + - 127.0.0.1 + - ::1 + server_host: 127.0.0.1 #Listen only to access from this IP, optional: restrict access to only via reverse proxy +``` + +## nginx Configuration + +Installation: See [Beginner's Guide to nginx Reverse Proxy](https://leetfs.com/tips/nginx) + +Get certificate: [Certbot Automated SSL Certificates](https://leetfs.com/tips/certbot) + +### WebSocket + +WebSocket must be enabled or access will not work properly + +``` + # Reverse proxy configuration + location / { + # Required WebSocket headers + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # Read and write timeout settings + proxy_read_timeout 86400; + proxy_send_timeout 86400; + + # Prevent Nginx from caching WebSocket data + proxy_buffering off; +``` + +### Example + +``` +server { + listen 443 ssl; # SSL listen + listen [::]:443 ssl; + + server_name your_domain; + + # SSL certificate path + ssl_certificate /etc/letsencrypt/live/; + ssl_certificate_key /etc/letsencrypt/live/; + + # Security optimization + ssl_protocols TLSv1.2 TLSv1.3; + ssl_prefer_server_ciphers on; + ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305'; + ssl_session_cache shared:SSL:10m; + + # HSTS (optional, enforces HTTPS) + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + + # Limit file upload size + client_max_body_size 20G; + + # Reverse proxy configuration + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Host $server_name; + + proxy_pass http://127.0.0.1:8123; # Backend service address + + # Enhance proxy security + proxy_set_header X-Frame-Options SAMEORIGIN; + proxy_set_header X-XSS-Protection "1; mode=block"; + proxy_set_header X-Content-Type-Options nosniff; + + # Required WebSocket headers + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # Read and write timeout settings + proxy_read_timeout 86400; + proxy_send_timeout 86400; + + # Prevent Nginx from caching WebSocket data + proxy_buffering off; + + # Restrict access, only allow access from LAN + # allow ip_here; # hk + # allow ip_here_as_well; #jp + # deny all; # deny all other requests + } +} +server { + listen 80; + listen [::]:80; + + server_name your_domain; + + return 301 https://$host$request_uri; # Permanently redirect to HTTPS +} +``` diff --git a/docs/en/tips/devops/index.md b/docs/en/tips/devops/index.md new file mode 100644 index 00000000..26ed9d53 --- /dev/null +++ b/docs/en/tips/devops/index.md @@ -0,0 +1,8 @@ +--- +title: DevOps +author: Lee +--- + +## Table of Contents + + diff --git a/docs/en/tips/devops/nginx.md b/docs/en/tips/devops/nginx.md new file mode 100644 index 00000000..3bfaed56 --- /dev/null +++ b/docs/en/tips/devops/nginx.md @@ -0,0 +1,127 @@ +--- +title: nginx Reverse Proxy Introduction +author: Lee +--- + +## Overview + +This tutorial is based on Debian, using nginx as a reverse proxy example for Docker containers already running. + +### Why use a reverse proxy? + +The following is information found online: + +A reverse proxy is a type of server that receives client requests, forwards them to web servers, and then returns the results to the client, as if the proxy server had directly handled the request itself. + +A reverse proxy proxies for servers, standing on the same side as the web servers.The real servers are invisible to clients.That is why it is called "reverse". + +Reverse proxy can be used for: + +Protecting servers by hiding their real IP addresses. +Load balancing: distributing requests among different servers according to traffic and server load. +Caching static content and handling large volumes of short-lived dynamic requests. +Serving as an application layer firewall for protection. +Encrypting/decrypting SSL communication. + +### For example + +For example, if we need to run three websites (a, b, c) on a server, all needing port 443, but the server has only one IP and can’t allocate three 443 ports. + +At this point, reverse proxy appears: nginx takes over port 443, and routes users accessing a.leetfs.com to site a, users accessing b.leetfs.com to site b, and similarly for c. + +## Installation + +1. Update the system index: `sudo apt update` +2. Install nginx: `sudo apt install nginx` + +After installation is complete, Nginx will automatically start and be set to launch on boot. You can check Nginx’s status with `sudo systemctl status nginx`. + +## Configure nginx + +- Default configuration file: `/etc/nginx/nginx.conf` +- Website configuration directory: `/etc/nginx/sites-available/` +- Directory storing enabled configuration files: `/etc/nginx/sites-enabled/` + +Next, we will configure nginx by modifying files in the `/etc/nginx/sites-available/` directory. + +## Reverse proxy to docker + +Our host runs the Weblate service via Docker. It would not be ideal for the container to directly take over the server's port 443, as this would restrict the port to only one service on the server. + +> You need to have some understanding of docker to read this section. + +### Configure the dockerfile + +Let's look at the container's dockerfile. `- 443:4443` under ports means the container listens on the server's port 443 and forwards received requests to port 4443 used by the docker container. + +```yaml +services: + weblate: + ports: + - 443:4443 + environment: +# ...more below +``` + +First, we change port 443, the standard https port, to another unused port on the server, e.g. `- 4443:4443`. After modifying, reload the container to apply the changes. + +## Modify nginx configuration file + +Switch to the website configuration directory: `/etc/nginx/sites-available/`. Create a new configuration file, named `weblate` in this example. + +Refer to the following code for the configuration file content: + +```nginx +server { + listen 443 ssl; # ssl means ssl encryption is used + listen [::]:443 ssl; + + server_name leetfs.com; # the domain to be reverse proxied + + ssl_certificate /var/lib/docker/volumes/weblate-docker_weblate-data/_data/ssl/fullchain.pem; # ssl certificate + ssl_certificate_key /var/lib/docker/volumes/weblate-docker_weblate-data/_data/ssl/privkey.pem; # ssl private key + + ssl_protocols TLSv1.2 TLSv1.3; # Enable TLSv1.2 and TLSv1.3, disable SSLv3 and outdated protocols + ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256'; # Recommended cipher suites + ssl_prefer_server_ciphers on; # Prefer server cipher suites + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto https; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Host $server_name; + + proxy_pass https://127.0.0.1:4443; # The reverse proxy destination, set to 4443 because we set the docker port above. 127.0.0.1 means the server itself. + + # Enhance proxy security + proxy_set_header X-Frame-Options SAMEORIGIN; + proxy_set_header X-XSS-Protection "1; mode=block"; + proxy_set_header X-Content-Type-Options nosniff; + } +} + +``` + +After modifying the configuration file, create a symbolic link to enable it (remember to change 'weblate' to your own file name). + +```bash +sudo ln -s /etc/nginx/sites-available/weblate /etc/nginx/sites-enabled/ +``` + +- Test if the configuration file is correct: `sudo nginx -t` +- Reload Nginx configuration: `sudo systemctl reload nginx` + +### Obtain the certificate + +For the `ssl_certificate` and `ssl_certificate_key` above, you need to fill in the certificate and private key paths. Refer to [Certbot: Automatically Obtain SSL Certificates](https://leetfs.com/tips/certbot). + +## Disable site configuration + +If you want to disable a site's configuration, you only need to delete the symbolic link, without deleting the actual file. This makes it easy to reuse later. + +```bash +sudo rm /etc/nginx/sites-enabled/filename +``` + +After finishing, remember to reload the Nginx configuration: `sudo systemctl reload nginx` diff --git a/docs/en/tips/front/cha-jian.md b/docs/en/tips/front/cha-jian.md new file mode 100644 index 00000000..fcc6d4dd --- /dev/null +++ b/docs/en/tips/front/cha-jian.md @@ -0,0 +1,11 @@ +--- +title: Recommended Practical Plugins +author: Lee +--- + +## LocatorJS + +Click on a component to go to its code, compatible with Vue, React, and more. + +Official Site: \ +GitHub: diff --git a/docs/en/tips/front/index.md b/docs/en/tips/front/index.md new file mode 100644 index 00000000..678f9386 --- /dev/null +++ b/docs/en/tips/front/index.md @@ -0,0 +1,8 @@ +--- +title: Frontend +author: Lee +--- + +## Table of Contents + + diff --git a/docs/en/tips/front/vp-font.md b/docs/en/tips/front/vp-font.md new file mode 100644 index 00000000..6c345f85 --- /dev/null +++ b/docs/en/tips/front/vp-font.md @@ -0,0 +1,22 @@ +--- +title: Vitepress Custom Font +author: Lee +--- + +## Method + +Place the font file in the `public` or `assets` folder. + +Edit `.vitepress/theme/style.css` and add the following at the end: + +```css +@font-face { + font-family: 'FontName'; + src: url('PathToFontFile') format('truetype'); +} + +:root { +--vp-font-family-base: "FontName";/* Other text font */ +--vp-font-family-mono: "FontName";/* Code block font */ +} +``` diff --git a/docs/en/tips/front/vp-fontSwitch.md b/docs/en/tips/front/vp-fontSwitch.md new file mode 100644 index 00000000..5aa1632d --- /dev/null +++ b/docs/en/tips/front/vp-fontSwitch.md @@ -0,0 +1,172 @@ +--- +title: Vitepress Navbar Font Switching +author: Lee +--- + +## Principle of Implementation + +Define a CSS variable and update the CSS variable when the navbar button is clicked + +## Add Button + +```ts +// docs/.vitepress/config.ts +// nav ... +{ + text: "Switch Font", + items: [ + { + text: "LXGW WenKai", + link: "#", // Since no jump is needed, we use an empty link + }, + { + text: "LXGW Neo XiHei", + link: "#", + }, + ], + }, + +``` + +## Import Fonts in CSS + +```css +@font-face { + font-family: 'LXGW WenKai'; + src: url('/LXGWWenKai-Regular.ttf') format('truetype'); +} +``` + +## Introduce CSS Variables in CSS + +Since the initial value of `--main-font` is empty before being assigned, we can use fallback font options as the `default font` + +```css +:root { +/* var(--main-font, 'Fallback Font') */ +--vp-font-family-base: var(--main-font, 'LXGW WenKai');/* Text font */ +--vp-font-family-mono: "LXGW WenKai Mono";/* Code font */ +} +``` + +## Listen to Button and Pass Font Name to CSS Variable + +Here we create a new JS script to listen for button clicks and update the CSS variable + +```js +// docs/.vitepress/theme/fontSwitcher.js +export const fontMap = { + 'LXGW WenKai': "'LXGW WenKai', serif", // 'Button Name':'Font Name', Fallback font (optional) + 'LXGW Neo XiHei': "'LXGW Neo XiHei', serif", + }; + + // Font switching function + export const switchFont = (font) => { + document.documentElement.style.setProperty('--main-font', fontMap[font]); + }; + + // Add global font switching event listener + export const addFontSwitchListener = () => { + // Normally, in Vitepress, dropdown content is wrapped in a span tag, please replace with ('.items span'), in this site, dropdowns are wrapped in a tag so use a + const fontSwitchItems = document.querySelectorAll('.items a'); // Select all 'a' tags in navbar items + // The following log is for debugging, if not effective you can uncomment the code below + // console.log(`Found ${fontSwitchItems.length} font switching items`); + fontSwitchItems.forEach(item => { + item.addEventListener('click', (e) => { + e.preventDefault(); + const target = e.target; + const selectedFont = target.innerText; // Get the clicked font name + // console.log(`${selectedFont}`); + switchFont(selectedFont); // Switch font + }); + }); +}; +``` + +> The above is an incorrect example. In Vitepress mobile view, the collapsed navbar is by default in a folded state. Only when the user expands it, the relevant resources are loaded; but the listener is created before this event, which leads to it not being able to listen successfully. + +### Correct Example + +```ts +export const fontMap = { + // Font mapping table + 'LXGW WenKai': 'LXGW WenKai', + 'LXGW WenKai Mono': 'LXGW WenKai Mono', + 'LXGW Neo XiHei': 'LXGW Neo XiHei', + 'NeoXiHei Code': 'NeoXiHei Code', + 'Default Font': 'system-ui', + 'Sarasa UI SC': 'Sarasa UI SC', + 'Source Han Serif CN': 'Source Han Serif CN', + 'Sans': 'sans', + 'Serif': 'serif', +}; + +// Font switching function +export const switchFont = (font) => { + document.documentElement.style.setProperty('--main-font', fontMap[font]); +}; + +// Add global font switching event listener +export const addFontSwitchListener = () => { + // Select hamburger menu + const hamburger = document.querySelector('.VPNavBarHamburger'); + const fontSwitchItems = document.querySelectorAll('.items a'); // Select all 'a' tags in navbar items + // console.log(`Found ${fontSwitchItems.length} font switching items`); + + fontSwitchItems.forEach(item => { + item.addEventListener('click', (e) => { + e.preventDefault(); + const target = e.target; + const selectedFont = target.innerText; // Get the clicked font name + // console.log(`${selectedFont}`); + switchFont(selectedFont); // Switch font + }); + }); + + // Add hamburger menu event listener + if (hamburger) { + hamburger.addEventListener('click', () => { + // Add font switching event listener when hamburger menu opens + const fontSwitchItems = document.querySelectorAll('.items a'); // Select all 'a' tags in navbar items + // console.log(`Found ${fontSwitchItems.length} font switching items`); + + fontSwitchItems.forEach(item => { + item.addEventListener('click', (e) => { + e.preventDefault(); + const target = e.target; + const selectedFont = target.innerText; // Get the clicked font name + // console.log(`${selectedFont}`); + switchFont(selectedFont); // Switch font + }); + }); + }); + } +}; + +``` + +## Import Script in index.ts/index.js + +```ts +// docs/.vitepress/theme/index.ts +// https://vitepress.dev/guide/custom-theme +import PtjsTheme from '@project-trans/vitepress-theme-project-trans/theme' +import { onMounted } from 'vue' +import { addFontSwitchListener } from './fontSwitcher' // Import script + +import 'uno.css' +import './style.css' + +export default { + extends: PtjsTheme, // This is my imported custom theme + setup() { + onMounted(() => { + addFontSwitchListener(); // Add font switching event listener + }); + }, +} +``` + +## Conclusion + +If it does not work, use the console to check whether the css file access path is correct, whether the script runs properly, and whether the button content is correctly obtained (see comments). diff --git a/docs/en/tips/git/git.md b/docs/en/tips/git/git.md new file mode 100644 index 00000000..a0ca3af5 --- /dev/null +++ b/docs/en/tips/git/git.md @@ -0,0 +1,60 @@ +--- +title: Simple Git Introduction +author: Lee +--- + +## Installation + +### Windows / macOS + + + +### Linux + +```bash +sudo apt update +sudo apt install git +``` + +## Usage + +After installation, you can run Git-related commands in any terminal, or use an editor like VS Code that has built-in Git plugins to visually manage Git. + +### Clone Repository + +```bash +git clone repository_url +``` + +```bash +git clone https://github.com/Leetfs/blog +``` + +Example: The URL of this repository is + +```bash +git clone https://github.com/Leetfs/blog ./lee-blog +``` + +By default, the cloned repository is placed in the current working directory, and the folder name defaults to the repository name.This command means placing the Git-cloned repository into the 'lee-blog' folder in this directory. + +> Tips: A path starting with / means starting from the root directory, for example, /lee means 'lee' under the root directory, and ./lee means 'lee' under the current working directory. + +### Working Directory + +When using Git, it's important to understand the concept of the [working directory](https://zh.wikipedia.org/wiki/%E5%B7%A5%E4%BD%9C%E7%9B%AE%E9%8C%84), which is the location where the current terminal or window is, and is also where some commands operate. + +For example, you can use `cd lee` to switch to the `lee` folder under the current directory. At this point, running `git clone` will clone the `blog` repository into the `lee` folder. + +### Stash / Push / Pull + +A common workflow: + +```bash +git pull # Pull the latest version +git add . # Stage all files in the folder +git commit -m "Put the commit message here, briefly describe what you changed, language is not limited. (Required)" # Commit staged changes +git push # Push to remote +``` + +Not finished yet, to be continued. diff --git a/docs/en/tips/git/github-pr.md b/docs/en/tips/git/github-pr.md new file mode 100644 index 00000000..e3c3d8a5 --- /dev/null +++ b/docs/en/tips/git/github-pr.md @@ -0,0 +1,44 @@ +--- +title: GitHub PR FAQ +author: Lee +--- + +## Overview + +This chapter is for common issues beginners may encounter. If you have any questions, feel free to [contact the author](https://github.com/Leetfs). + +## What should I do if there are new commits in the repository before my PR is merged? + +If there are no merge conflicts, you can ignore it; if there are merge conflicts, you need to resolve them first. + +## After my PR is merged, I want to submit a new PR + +Be sure not to commit directly to the original branch, as this may cause merge conflicts. + +### Solution 1 + +You can update the branch to the latest version + +(Both buttons are effective. The first one updates to the latest version and discards your local commits, while the second updates to the latest version) +![](/tips/git/github-img/image11.png) + +### Solution 2 + +Create a new branch based on the upstream repository and commit in the new branch + +![](/tips/git/github-img/image12.png) +![](/tips/git/github-img/image13.png) + +## How to modify after submission + +Before the PR is merged, the branch and PR are bound together; just modify the corresponding branch directly. + +## How to review a PR + +Go into the PR and click on `Files changed` + +![](/tips/git/github-img/image14.png) + +Click on `Review changes` + +![](/tips/git/github-img/image15.png) diff --git a/docs/en/tips/git/github.md b/docs/en/tips/git/github.md new file mode 100644 index 00000000..2e38bde4 --- /dev/null +++ b/docs/en/tips/git/github.md @@ -0,0 +1,76 @@ +--- +title: A Beginner's Guide to Contributing on GitHub +author: Lee +--- + +### Required Tools + +- VS Code (optional) +- Git (optional) +- A browser + +## GitHub + +### Getting Started with GitHub + +GitHub is a large open-source community where you can freely contribute to projects you like. + +GitHub Official Website: + +### How do I contribute? + +Register an account (details omitted here) + +Go to the homepage and use the search bar to find the repository you want to contribute to, or jump directly via a repository link. + +![](/tips/git/github-img/image.png) + +On the repository code page (homepage), click Fork to copy the repository to your account. + +![](/tips/git/github-img/image1.png) ![](/tips/git/github-img/image2.png) + +Go to your forked repository + +![](/tips/git/github-img/image3.png) + +Find the file you want to edit, make your changes, and then click Save in the upper right corner. + +![](/tips/git/github-img/image4.png) ![](/tips/git/github-img/image5.png) + +After all files have been modified, return to the repository homepage and initiate a pull request. + +![](/tips/git/github-img/image6.png) ![](/tips/git/github-img/image7.png) + +Enter your title (required) and description (optional), then click Send. + +![](/tips/git/github-img/image8.png) + +Wait for the upstream repository maintainer to merge your pull request + +### Tips + +On a GitHub repository page, pressing the `.` key switches to the web version of VS Code, where editing can sometimes be more convenient than the native editor. + +> You can practice with [this repository](https://github.com/Leetfs/blog); start by adding missing punctuation or correcting typos~ + +## FAQ + +These are questions commonly encountered when teaching newcomers. This section is continuously updated. + +### What if I can't find my forked repository? + +Click your avatar in the upper right corner, then select `Your repositories` from the sidebar that appears. + +![](/tips/git/github-img/image9.png) + +On the page, select the repository you want to switch to. + +![](/tips/git/github-img/image10.png) + +**Note:** + +> Clicking the `Forked from ...` below the repository name will jump to the upstream repository, but usually you can only push changes to upstream via PR (pull request) unless you have direct push access to the upstream repository. + +## About pushing with VS Code and Git + +See other articles in this series diff --git a/docs/en/tips/git/index.md b/docs/en/tips/git/index.md new file mode 100644 index 00000000..eb4e68a7 --- /dev/null +++ b/docs/en/tips/git/index.md @@ -0,0 +1,12 @@ +--- +title: Git & GitHub +author: Lee +--- + +## Introduction + +This is a Git and GitHub tutorial for beginners~ + +## Table of Contents + + diff --git a/docs/en/tips/gpgpu/index.md b/docs/en/tips/gpgpu/index.md new file mode 100644 index 00000000..3cdc1862 --- /dev/null +++ b/docs/en/tips/gpgpu/index.md @@ -0,0 +1,12 @@ +--- +title: GPGPU +author: Lee +--- + +## Introduction + +Use the GPU for general-purpose computing. + +## Table of Contents + + diff --git a/docs/en/tips/gpgpu/lit-ll.md b/docs/en/tips/gpgpu/lit-ll.md new file mode 100644 index 00000000..83d5d0a5 --- /dev/null +++ b/docs/en/tips/gpgpu/lit-ll.md @@ -0,0 +1,64 @@ +--- +title: Use lit to test LLVM IR files +author: Lee +--- + +## Term Match + +- lit: LLVM Integrated Tester +- .ll: LLVM IR file + +## Prerequisites + +llvm installed + +## Test Process + +```yaml +float.ll + | + v +lit executes RUN command -> llc generates output + | + v +FileCheck verifies output + | + +--✔️ All match: PASS + | + +--❌ Error: FAIL +``` + +## Execution Statement + +You can specify a single file or a directory. + +```bash +llvm-lit llvm/test/CodeGen/RISCV/VentusGPGPU/float.ll +``` + +## Output + +```bash +-- Testing: 1 tests, 1 workers -- +PASS: LLVM :: CodeGen/RISCV/VentusGPGPU/float.ll (1 of 1) + +Testing Time: 0.07s + Passed: 1 +``` + +## Common Commands + +| Command | Description | Example | +| ------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------- | +| `llvm-lit ` | Run all test cases in the specified directory | `llvm-lit ./test` | +| `-v` or `--verbose` | Show detailed test output | `llvm-lit -v ./test` | +| `-j ` or `--jobs=` | Specify the number of tests to run in parallel | `llvm-lit -j 4 ./test` | +| `--max-tests ` | Limit the maximum number of tests to run | `llvm-lit --max-tests=100 ./test` | +| `--filter=` | Run tests that match the given pattern (filter by test name) | `llvm-lit --filter=xyz ./test` | +| `--show-unsupported` | Display unsupported tests | `llvm-lit --show-unsupported ./test` | +| `--test-messages` | Show detailed output of each test (includes stdout and stderr) | `llvm-lit --test-messages ./test` | +| `--help` | Show the help documentation of `llvm-lit`, listing all supported options and parameters | `llvm-lit --help` | +| `--dump-input=help` | If the test fails, display the input to help debug the failure | `llvm-lit --dump-input=help ./test` | +| `--continue-on-error` | Continue running other tests without stopping if a test fails | `llvm-lit --continue-on-error ./test` | +| `--output=` | Output test results to the specified file | `llvm-lit --output=result.txt ./test` | +| `--no-filecheck` | Disable the generation of `FileCheck` output | `llvm-lit --no-filecheck ./test` | diff --git a/docs/en/tips/gpgpu/trition-report.md b/docs/en/tips/gpgpu/trition-report.md new file mode 100644 index 00000000..2fe079cc --- /dev/null +++ b/docs/en/tips/gpgpu/trition-report.md @@ -0,0 +1,35 @@ +--- +title: Triton Usage Experience and Performance Analysis +author: Lee +--- + +## Overview + +Triton is a GPGPU programming framework optimized for deep learning. **Simple and high-performance**, efficiently developed using the Python environment~ + +## Installation and Usage + +Use pip. + +```bash +uv pip install triton +``` + +```python +import triton + +@triton.jit +... +``` + +## Performance Optimization + +### Adjust Thread Block Size + +#### vecadd: BLOCK_SIZE = 16 + +![](/tips/gpgpu/images/trition-report/vector-add-performance-16.png) + +#### vecadd: BLOCK_SIZE = 32 + +![](/tips/gpgpu/images/trition-report/vector-add-performance-32.png) diff --git a/docs/en/tips/gpgpu/ventus-llvm-install.md b/docs/en/tips/gpgpu/ventus-llvm-install.md new file mode 100644 index 00000000..9def71f1 --- /dev/null +++ b/docs/en/tips/gpgpu/ventus-llvm-install.md @@ -0,0 +1,64 @@ +--- +title: Chengying GPGPU LLVM Compiler Installation Notes +author: Lee +--- + +## Introduction + +Chengying GPGPU is a **GPGPU architecture for RISC-V**.\ +This article references this repository: . + +## Install dependencies + +```bash +sudo apt install -y git build-essential clang cmake ninja-build ccache zlib1g-dev libtool autoconf automake device-tree-compiler bsdmainutils ruby clinfo +``` + +## Download files + +:::tip +Create a folder and clone all the repositories into this directory. In the following, `J142` is used as the folder name. +::: + +- llvm-ventus : `git clone https://github.com/THU-DSP-LAB/llvm-project.git` +- pocl : `git clone https://github.com/THU-DSP-LAB/pocl.git` +- ocl-icd : `git clone https://github.com/OCL-dev/ocl-icd.git` +- isa-simulator(spike) : `git clone https://github.com/THU-DSP-LAB/ventus-gpgpu-isa-simulator.git` +- driver : `git clone https://github.com/THU-DSP-LAB/ventus-driver.git` +- rodinia : `git clone https://github.com/THU-DSP-LAB/gpu-rodinia.git` + +## Set environment variables + +```bash +export VENTUS_INSTALL_PREFIX=/root/J142/llvm-project/install +export SPIKE_TARGET_DIR=${VENTUS_INSTALL_PREFIX} +export LD_LIBRARY_PATH=${VENTUS_INSTALL_PREFIX}/lib +export OCL_ICD_VENDORS=${VENTUS_INSTALL_PREFIX}/lib/libpocl.so +export POCL_DEVICES="ventus" +export PATH=/root/J142/llvm-project/build/bin:$PATH +``` + +## Build the compiler + +```bash +cd J142/llvm-project +./build-ventus.sh +``` + +## Check installation status + +```bash +cd J142/pocl/build/bin +./poclcc -l +``` + +![](/tips/gpgpu/images/llvm-img/poclcc.png) + +## Run the test cases + +```bash +cd J142/pocl/build/examples/vecadd +./vecadd +``` + +![](/tips/gpgpu/images/llvm-img/vecadd.png) diff --git a/docs/en/tips/gpgpu/zvfhmin-report.md b/docs/en/tips/gpgpu/zvfhmin-report.md new file mode 100644 index 00000000..c853bfff --- /dev/null +++ b/docs/en/tips/gpgpu/zvfhmin-report.md @@ -0,0 +1,65 @@ +--- +title: RISC-V Zvfh(min) Extension Support Research Report (LLVM CodeGen Phase) +author: Lee +--- + +## Copyright Notice + +This article was originally published at [xlinsist/llvm-project Issue #2](https://github.com/xlinsist/llvm-project/issues/2) by myself as the original author.Follows the original repository license [Apache License 2.0](https://github.com/xlinsist/llvm-project/blob/main/LICENSE.TXT).Based on this, it is reposted and slightly revised on this blog. + +## Overview + +### Research Goals + +- Add support for the Zvfh(min) extension in ventus-llvm + +### Development Background + +- Add support for 16-bit half-precision floating-point data type to Chengying +- The project goal is to gradually support the half type, including scalar (Zhinx(min)) and vector (Zvfh(min)) +- The Zhinx(min) extension has completed initial integration and is under PR review and revision stages + +### Requirement Analysis + +- Half has lower precision and range, and offers smaller memory usage and higher throughput + +## Official Zvfh(min) Patch Summary + +- Patch address: [D151414](https://reviews.llvm.org/D151414) +- Related files: + - `RISCVISAInfo.cpp` + - `RISCVFeatures.td` + - `RISCVISelLowering.cpp` + - `RISCVInstrInfoVPseudos.td` + - `RISCVInstrInfoVSDPatterns.td` + - `RISCVInstrInfoVVLPatterns.td` + - `RISCVSubtarget.h` + - `**.ll` +- Main modifications: + - Register zvfhmin + - Add type/instruction legalization for f16 + - Handle `vfwcvt.f.f.v` and `vfncvt.f.f.w` instructions for f16 + - Determine whether the current device supports f16 vector instructions + - Add SDNode and machine instruction mapping related to f16 + - Add test cases + +## File modifications + +| File Path | Modification Target | +| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `llvm/lib/Support/RISCVISAInfo.cpp` | Register the zvfhmin instruction set extension into the extension table | +| `llvm/lib/Target/RISCV/RISCV.td` | Add the zvfhmin feature and match dependency zve32f `[FeatureStdExtZve32f]` | +| `llvm/lib/Target/RISCV/RISCVInstrInfoVPseudos.td & RISCVInstrInfoVSDPatterns.td` | Add Zvfh(min) instructions and matching Patterns | +| `llvm/lib/Target/RISCV/RISCVISelLowering.cpp` | Introduce MVT::f16 type and operation support, ensure that MVT::f16 vector types are only allowed when Zvfhmin is enabled | +| `llvm/test/CodeGen/RISCV/VentusGPGPU/half.ll` | Add test cases | + +## Test Cases + +| Type | Purpose | Example | +| ---------------------- | ------------------------------------------------------------------ | ------------------------------- | +| Instruction Generation | Verify whether half-precision instructions are generated correctly | Rewrite `float.ll` to `half.ll` | +| Type Conversion | Conversion between half and float32 | `vfwcvt.f.f.v`, `vfncvt.f.f.w` | + +## Supplement + +Zvfhmin only supports conversion (`vfwcvt.f.f.v f16=>f32`, `vfncvt.f.f.w f32=>16`) and does not support direct half-precision vector arithmetic operations. For arithmetic operations, zvfh is required. diff --git a/docs/en/tips/index.md b/docs/en/tips/index.md index 632a58be..61c367c4 100644 --- a/docs/en/tips/index.md +++ b/docs/en/tips/index.md @@ -1,12 +1,12 @@ --- -title: 一些经验 +title: Some Experience icon: creative author: Lee category: - - 一些经验 + - Some Experience index: false --- -## 目录 +## Contents diff --git a/docs/en/tips/jenkins/index.md b/docs/en/tips/jenkins/index.md new file mode 100644 index 00000000..c1446646 --- /dev/null +++ b/docs/en/tips/jenkins/index.md @@ -0,0 +1,8 @@ +--- +title: Jenkins +author: Lee +--- + +## Table of Contents + + diff --git a/docs/en/tips/jenkins/jenkins-css.md b/docs/en/tips/jenkins/jenkins-css.md new file mode 100644 index 00000000..631517a4 --- /dev/null +++ b/docs/en/tips/jenkins/jenkins-css.md @@ -0,0 +1,25 @@ +--- +title: Jenkins allows loading inline CSS styles +author: Lee +--- + +## Groovy Script + +Jenkins security policy: + +- No JavaScript allowed at all +- No plugins (object/embed) allowed +- No inline CSS, or CSS from other sites allowed +- No images from other sites allowed +- No frames allowed +- No web fonts allowed +- No XHR/AJAX allowed +- etc. + +By default, only internal server resources are allowed. To allow inline styles, execute the following code in Manage Jenkins -> Script Console, or use Pipeline + Groovy plugin to execute during the process. + +```Groovy +System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "sandbox allow-same-origin; default-src 'self'; style-src 'self' 'unsafe-inline';") +``` + +For more details, please refer to the [official documentation](https://www.jenkins.io/doc/book/security/configuring-content-security-policy/) diff --git a/docs/en/tips/jenkins/jenkins-pipeline.md b/docs/en/tips/jenkins/jenkins-pipeline.md new file mode 100644 index 00000000..b00a9afe --- /dev/null +++ b/docs/en/tips/jenkins/jenkins-pipeline.md @@ -0,0 +1,81 @@ +--- +title: Jenkins Declarative Pipeline and Scripted Pipeline +author: Lee +--- + +## Declarative Pipeline + +_Jenkinsfile (Declarative Pipeline)_ + +```groovy +pipeline { + agent any // Allows running on any node; can also use none to not specify a global agent. + stages { + stage('Build') { + agent { // Specify agent node + label 'master' + } + steps { + // + } + } + stage('Test') { + steps { + // + } + } + stage('Deploy') { + steps { + // + } + } + } +} +``` + +Each stage can only have one steps block, and the execution node for the stage can be specified with `agent { label 'master' }`. + +### Features of Declarative Pipeline + +1. When different stages use the same label, the execution node may not be the same. Jenkins will randomly assign an available node with that label. +2. When managing Jenkinsfile with a version control system, the Declarative Pipeline will check out the entire repository to the root directory for every stage, so git must be installed on the agent nodes. +3. Within the same steps block, the context is inherited from previous steps. For example, if the first line is `sh 'cd nya'`, the next line will have its working path inside nya. + +### Solution for Feature 1 + +When first calling the node, assign `env.NODE_NAME` to a global variable, and add the defined variable to the label tag where this node is needed. + +`env.NODE_NAME` is a built-in Jenkins variable. Its value is the name of the node running the current stage. + +## Scripted Pipeline + +_Jenkinsfile (Scripted Pipeline)_ + +```groovy +node('master') { // Specify node with master label + stage('Build') { + // + } + stage('Test') { + // + } +} +node('RVV') { // Specify node with RVV label + stage('Build') { + // + } + stage('Test') { + sh 'meow' + sh 'meow' + } +} +``` + +Simple and convenient, with no complicated `pipeline` framework, it uses node blocks to control node execution.Usage Example: + +### Features of Scripted Pipeline + +1. A pipeline can have multiple nodes. A node can be specified for multiple stages at once, and stages in the same node block will run on the same node. +2. When managing Jenkinsfile with a version control system, the Scripted Pipeline will not check out the entire repository to the node, it only reads the Jenkinsfile. If you want to use the repository, you need to clone it manually. +3. Within the same steps block, the context is not inherited from previous steps. For example, if the first line is `sh 'cd nya'`, the second line's working directory is still the default workspace path, not nya. + - This does not apply to multi-line scripts like `sh ''' I am the content ''' `, since all commands inside the multi-line block run in a single sh context. diff --git a/docs/en/tips/languages/index.md b/docs/en/tips/languages/index.md new file mode 100644 index 00000000..840594d7 --- /dev/null +++ b/docs/en/tips/languages/index.md @@ -0,0 +1,8 @@ +--- +title: Languages +author: Lee +--- + +## Table of Contents + + diff --git a/docs/en/tips/languages/python/index.md b/docs/en/tips/languages/python/index.md new file mode 100644 index 00000000..3cd11bfd --- /dev/null +++ b/docs/en/tips/languages/python/index.md @@ -0,0 +1,8 @@ +--- +title: Python +author: Lee +--- + +## Table of Contents + + diff --git a/docs/en/tips/languages/python/numba.md b/docs/en/tips/languages/python/numba.md new file mode 100644 index 00000000..4081aa7b --- /dev/null +++ b/docs/en/tips/languages/python/numba.md @@ -0,0 +1,26 @@ +--- +title: Numba +author: Lee +--- + +## Introduction + +Automatically compile Python functions into high-performance machine code using `@jit` or `@njit`. + +## Installation + +```bash +pip install numba +``` + +## Usage Example + +```python{1,3} +from numba import njit + +@njit +def add(a, b): + return a + b + +print(add(1, 2)) # Output: 3 +``` diff --git a/docs/en/tips/languages/python/uv.md b/docs/en/tips/languages/python/uv.md new file mode 100644 index 00000000..67b15c6c --- /dev/null +++ b/docs/en/tips/languages/python/uv.md @@ -0,0 +1,74 @@ +--- +title: uv package manager +author: Lee +--- + +## Introduction + +[uv](https://docs.astral.sh/uv/) is a **next-generation** Python package management tool + +## Installation + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +## Create a virtual environment + +```bash +uv venv +``` + +## Install/Uninstall packages + +Add uv before the pip command + +```bash +uv pip install triton +uv pip uninstall triton +``` + +## Manage dependencies + +### Install/Uninstall dependencies + +```bash +uv pip install requests +uv pip uninstall requests +``` + +### Install from requirements.txt + +```bash +uv pip install -r requirements.txt +``` + +### Freeze dependency list + +```bash +uv pip freeze > requirements.txt +``` + +### Update all dependencies + +```bash +uv pip install -U -r requirements.txt +``` + +## Run Python script + +```bash +uv run script.py +``` + +## Start REPL + +```bash +uv +``` + +## Clean cache + +```bash +uv cache clean +``` diff --git a/docs/en/tips/misc/epic.md b/docs/en/tips/misc/epic.md new file mode 100644 index 00000000..1c947c33 --- /dev/null +++ b/docs/en/tips/misc/epic.md @@ -0,0 +1,22 @@ +--- +title: Display EpicGames on profile page +author: Lee +--- + +## Usage + +There are many members in the EpicGames organization, so you may not be able to find yourself on the members page, which prevents you from setting your status. + +You can run the following code on any terminal. + +## Public + +```shell +Invoke-RestMethod -Uri "https://api.github.com/orgs/EpicGames/public_members/your-username" -Method Put -Headers @{"Accept"="application/vnd.github.v3+json"; "Authorization"="token your-PAT-token"} +``` + +## Hide + +```shell +Invoke-RestMethod -Uri "https://api.github.com/orgs/EpicGames/public_members/your-username" -Method Delete -Headers @{"Authorization"="token your-PAT-token"} +``` diff --git a/docs/en/tips/misc/index.md b/docs/en/tips/misc/index.md new file mode 100644 index 00000000..e52bea3a --- /dev/null +++ b/docs/en/tips/misc/index.md @@ -0,0 +1,8 @@ +--- +title: Miscellaneous +author: Lee +--- + +## Table of Contents + + diff --git a/docs/en/tips/risc-v/index.md b/docs/en/tips/risc-v/index.md new file mode 100644 index 00000000..1bc88ce7 --- /dev/null +++ b/docs/en/tips/risc-v/index.md @@ -0,0 +1,8 @@ +--- +title: RISC-V +author: Lee +--- + +## Table of Contents + + diff --git a/docs/en/tips/risc-v/qemu.md b/docs/en/tips/risc-v/qemu.md new file mode 100644 index 00000000..deced48d --- /dev/null +++ b/docs/en/tips/risc-v/qemu.md @@ -0,0 +1,16 @@ +--- +title: Run RISC-V programs with QEMU +author: Lee +--- + +## Installation + +```bash +apt install qemu-user +``` + +## Usage + +```bash +qemu-riscv64 ./hello +``` diff --git a/docs/en/tips/risc-v/riscv-gnu-toolchain.md b/docs/en/tips/risc-v/riscv-gnu-toolchain.md new file mode 100644 index 00000000..fc73315f --- /dev/null +++ b/docs/en/tips/risc-v/riscv-gnu-toolchain.md @@ -0,0 +1,85 @@ +--- +title: RISC-V GNU Compiler Toolchain +author: Lee +--- + +## Prerequisites + +This article uses the precompiled version. If you want to build it yourself, please refer to the official documentation. + +## Installation + +- Go to the [releases](https://github.com/riscv-collab/riscv-gnu-toolchain/releases) page and select a suitable package. +- Extract the downloaded file to `/opt`, and add `/opt/riscv/bin` to `PATH`. + +```bash +curl -fL https://github.com/riscv-collab/riscv-gnu-toolchain/releases/download/2025.01.20/riscv64-glibc-ubuntu-22.04-gcc-nightly-2025.01.20-nightly.tar.xz -o /tmp/riscv64-toolchain.tar.xz # Download + +tar -xf /tmp/riscv64-toolchain.tar.xz -C /opt/ #Extract + +rm /tmp/riscv64-toolchain.tar.xz # Remove archive + +export PATH=/opt/riscv/bin:$PATH # Set environment variable +``` + +You can use the following commands to test if the installation is correct (the following commands are for the glibc toolchain; refer to the documentation for other versions). + +```bash +riscv64-unknown-linux-gnu-gcc --version +riscv64-unknown-linux-gnu-g++ --version +riscv64-unknown-linux-gnu-gfortran --version +riscv64-unknown-linux-gnu-objdump --version +riscv64-unknown-linux-gnu-gdb --version +``` + +### Installation in Docker + +It is recommended to use a Dockerfile. + +```dockerfile +# Download and extract the cross-compilation toolchain +RUN curl -fL https://github.com/riscv-collab/riscv-gnu-toolchain/releases/download/2025.01.20/riscv64-glibc-ubuntu-22.04-gcc-nightly-2025.01.20-nightly.tar.xz -o /tmp/riscv64-toolchain.tar.xz && \ + tar -xf /tmp/riscv64-toolchain.tar.xz -C /opt/ && \ + rm /tmp/riscv64-toolchain.tar.xz + +# Set cross-compilation toolchain path +ENV PATH=/opt/riscv/bin:$PATH +``` + +## Usage + +You can use this toolchain with cmake to cross-compile RISC-V programs. + +- Create a `toolchain-riscv64.cmake` (or any name you prefer) file as the CMake cross-compilation configuration file. +- Use `cmake -D CMAKE_TOOLCHAIN_FILE=path/to/toolchain-riscv64.cmake` to specify this file. +- Run `make -j $(nproc)` to build the binary program. + +Below is my `toolchain-riscv64.cmake` template + +```cmake +# Set the target architecture for cross compilation +set(CMAKE_SYSTEM_NAME Linux) +set(CMAKE_SYSTEM_PROCESSOR riscv64) + +# Set the path to the cross-compilation toolchain +set(tools /opt/riscv) + +# Set the C and C++ compilers +set(CMAKE_C_COMPILER ${tools}/bin/riscv64-unknown-linux-gnu-gcc) +set(CMAKE_CXX_COMPILER ${tools}/bin/riscv64-unknown-linux-gnu-g++) + +# Set sysroot (if any) +set(CMAKE_SYSROOT /opt/riscv/sysroot) + +# Configure search paths +set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT}) +set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) +set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) +set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) + +# Use static linking +set(CMAKE_EXE_LINKER_FLAGS "-static") +# set(CMAKE_CXX_FLAGS "-static -O3") #Enable optimization +# set(CMAKE_C_FLAGS "-static -O3") +set(BUILD_SHARED_LIBS OFF) +``` diff --git a/docs/en/tips/system/index.md b/docs/en/tips/system/index.md new file mode 100644 index 00000000..2fc9c185 --- /dev/null +++ b/docs/en/tips/system/index.md @@ -0,0 +1,8 @@ +--- +title: System +author: Lee +--- + +## Contents + + diff --git a/docs/en/tips/system/linux/bbr.md b/docs/en/tips/system/linux/bbr.md new file mode 100644 index 00000000..af77118f --- /dev/null +++ b/docs/en/tips/system/linux/bbr.md @@ -0,0 +1,21 @@ +--- +title: Enable BBR Congestion Control Algorithm on Debian +author: Lee +--- + +## Manual Method + +Edit the `etc/sysctl.conf` file and add the following at the end: + +```text +net.core.default_qdisc=fq +net.ipv4.tcp_congestion_control=bbr +``` + +Run `sysctl -p` to save and apply the changes + +## Automatic Method + +```text +echo -e "\nnet.core.default_qdisc=fq\nnet.ipv4.tcp_congestion_control=bbr" >> /etc/sysctl.conf && sysctl -p +``` diff --git a/docs/en/tips/system/linux/env-variables.md b/docs/en/tips/system/linux/env-variables.md new file mode 100644 index 00000000..cd8fd036 --- /dev/null +++ b/docs/en/tips/system/linux/env-variables.md @@ -0,0 +1,22 @@ +--- +title: Persist environment variables +author: Lee +--- + +## Configuration + +Open `.bashrc` + +```bash +nano ~/.bashrc +``` + +Add the `export` statements at the end + +```bash +export VENTUS_INSTALL_PREFIX=/root/J142/llvm-project/install +export SPIKE_TARGET_DIR=${VENTUS_INSTALL_PREFIX} +export LD_LIBRARY_PATH=${VENTUS_INSTALL_PREFIX}/lib +export OCL_ICD_VENDORS=${VENTUS_INSTALL_PREFIX}/lib/libpocl.so +export POCL_DEVICES="ventus" +``` diff --git a/docs/en/tips/system/linux/gpg-sign.md b/docs/en/tips/system/linux/gpg-sign.md new file mode 100644 index 00000000..ccefabed --- /dev/null +++ b/docs/en/tips/system/linux/gpg-sign.md @@ -0,0 +1,50 @@ +--- +title: Fix GPG signature errors in terminal environments +author: Lee +--- + +## Troubleshooting + +When connecting to the server via terminal and using the GPG key within Yubikey to sign Git commits, an error appears. Brief troubleshooting steps: + +![](/tips/system/linux/pubilc/gpg-sign-img/gpg-sign-1.png) + +Verify if there is a valid private key: + +```bash +gpg --list-secret-keys --keyid-format LONG +``` + +![](/tips/system/linux/pubilc/gpg-sign-img/gpg-sign-2.png) + +Test whether the smart card can be read correctly: + +```bash +gpg --card-status +``` + +![](/tips/system/linux/pubilc/gpg-sign-img/gpg-sign-3.png) + +Test signing directly with GPG: + +```bash +echo \"test\" | gpg --clearsign +``` + +Receive the output: + +```bash +-----BEGIN PGP SIGNED MESSAGE-----\nHash: SHA256\n\ntest\ngpg: signing failed: Inappropriate ioctl for device\ngpg: [stdin]: clear-sign failed: Inappropriate ioctl for device +``` + +Observing the error, it is found that in multi-terminal environments, GPG cannot automatically recognize the current terminal device in use, resulting in the inability to correctly prompt the user for PIN input. Try to fix by configuring the GPG_TTY environment variable: + +```bash +export GPG_TTY=$(tty) +``` + +Retest signing: + +![](/tips/system/linux/pubilc/gpg-sign-img/gpg-sign-4.png) + +The verification prompt appears successfully, and the issue is resolved. diff --git a/docs/en/tips/system/linux/index.md b/docs/en/tips/system/linux/index.md new file mode 100644 index 00000000..d3862aca --- /dev/null +++ b/docs/en/tips/system/linux/index.md @@ -0,0 +1,8 @@ +--- +title: Linux +author: Lee +--- + +## Table of Contents + + diff --git a/docs/en/tips/system/linux/install-cuda.md b/docs/en/tips/system/linux/install-cuda.md new file mode 100644 index 00000000..d7aff2f3 --- /dev/null +++ b/docs/en/tips/system/linux/install-cuda.md @@ -0,0 +1,33 @@ +--- +title: Install CUDA Toolkit +author: Lee +--- + +## Installation + +Go to the [official website](https://developer.nvidia.com/cuda-downloads) to choose the appropriate package. + +## Environment Variables + +```bash +export PATH=/usr/local/cuda-12.8/bin:$PATH +export CUDADIR=/usr/local/cuda-12.8 +export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/cuda-12.8/lib64 +export CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:/usr/local/cuda-12.8/include +``` + +## Test Installation Status + +```bash +nvcc --version +``` + +### Return + +```text +nvcc: NVIDIA (R) Cuda compiler driver +Copyright (c) 2005-2025 NVIDIA Corporation +Built on Fri_Feb_21_20:23:50_PST_2025 +Cuda compilation tools, release 12.8, V12.8.93 +Build cuda_12.8.r12.8/compiler.35583870_0 +``` diff --git a/docs/en/tips/system/linux/install-docker.md b/docs/en/tips/system/linux/install-docker.md new file mode 100644 index 00000000..6e19dd28 --- /dev/null +++ b/docs/en/tips/system/linux/install-docker.md @@ -0,0 +1,71 @@ +--- +title: Install Docker on Debian +author: Lee +--- + +## Install docker + +### Update package index + +```bash +sudo apt update +``` + +### Install dependencies + +```bash +sudo apt install apt-transport-https ca-certificates curl software-properties-common +``` + +### Add Docker official GPG key + +```bash +curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg +``` + +### Add Docker official APT repository + +```bash +echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +``` + +### Update index again + +```bash +sudo apt update +``` + +### Install Docker + +```bash +sudo apt install docker-ce docker-ce-cli containerd.io +``` + +### Start and enable on boot + +```bash +sudo systemctl start docker +sudo systemctl enable docker +``` + +### Check if running properly + +```bash +sudo docker --version +``` + +A correct installation will output the version number + +## Install Docker Compose + +Optional, install as needed + +```bash +sudo apt install docker-compose +``` + +After installation, run the following command to verify: + +```bash +docker-compose --version +``` diff --git a/docs/en/tips/system/linux/linux-dns.md b/docs/en/tips/system/linux/linux-dns.md new file mode 100644 index 00000000..5182ef8b --- /dev/null +++ b/docs/en/tips/system/linux/linux-dns.md @@ -0,0 +1,58 @@ +--- +title: Linux Change DNS +author: Lee +--- + +## Confirm DNS management program + +Run `cat /etc/resolv.conf` and check the file output for comments like `# Generated by resolvconf` or `# Generated by systemd-resolved`. + +## Directly modify resolv.conf + +Suitable for cases where DNS is not taken over or when you want to temporarily modify it even if it is. + +Open `etc/resolv.conf` and modify the `nameserver` parameter, for example: + +```text +nameserver 1.1.1.1 +nameserver 1.0.0.1 +nameserver 2606:4700:4700::1111 +nameserver 2606:4700:4700::1001 +``` + +## Modify via systemd-resolved + +Open `etc/systemd/resolved.conf` and edit the `DNS=` parameter, for example: + +```text +DNS= 1.1.1.1 1.0.0.1 2606:4700:4700::1111 2606:4700:4700::1001 +``` + +Run `sudo systemctl restart systemd-resolved.service` to restart the DNS service. + +## Modify via resolvconf + +Open the resolvconf configuration file. + +```bash +nano /etc/resolvconf/resolv.conf.d/head +``` + +Edit the configuration. + +```text +nameserver 8.8.8.8 +nameserver 8.8.4.4 +``` + +Regenerate resolv.conf + +```bash +sudo resolvconf -u +``` + +Run the following command to verify the DNS configuration + +```bash +cat /etc/resolv.conf +``` diff --git a/docs/en/tips/system/linux/ssh-agent.md b/docs/en/tips/system/linux/ssh-agent.md new file mode 100644 index 00000000..2df9135e --- /dev/null +++ b/docs/en/tips/system/linux/ssh-agent.md @@ -0,0 +1,44 @@ +--- +title: ssh agent forwarding +author: Lee +--- + +## Use Cases + +During development, to use SSH keys more securely on remote servers, it is recommended to invoke local keys through SSH agent forwarding, instead of storing the keys directly on the server.This can effectively reduce the risk of key leakage and improve overall security. + +## Configuration + +### Verify Local Setup + +First, ensure that your local ssh is running correctly. You can use the `ssh-add -l` command to list all ssh keys, or use `ssh -T` to test if access works properly. + +![](/tips/system/linux/pubilc/ssh-agent-1.png) + +### Set up ssh agent forwarding + +Open the `User folder/.ssh/config` file and add `ForwardAgent yes` under the server configuration where you want to enable ssh agent forwarding. + +Example: + +```text{4} +Host test-server + HostName your-server-address-here + User root + ForwardAgent yes +``` + +You can also enable this globally: + +```text +Host * + ForwardAgent yes +``` + +After setup, you can run `ssh-add -l` on the server to list all ssh keys. If it does not work, check that the `AllowAgentForwarding` option in `etc/ssh/sshd_config` on the server is correctly set to `yes`. + +### Security Notice + +:::warning +The server cannot access the keys directly, but once the connection is established, it can use the keys as if it were you. Only add trusted servers or use solutions like 1Password agent requiring secondary authentication to ensure security. +::: diff --git a/docs/en/tips/system/linux/ssh-login.md b/docs/en/tips/system/linux/ssh-login.md new file mode 100644 index 00000000..9a5b0dc4 --- /dev/null +++ b/docs/en/tips/system/linux/ssh-login.md @@ -0,0 +1,26 @@ +--- +title: Log in to the server using SSH keys and disable password login +author: Lee +--- + +## Configure SSH key login + +- Generate a key pair using the command `ssh-keygen` or use an existing key pair +- Copy the corresponding public key to the `root/.ssh/authorized_keys` file. + +## Disable password login + +Edit the /etc/ssh/sshd_config file and modify the following parameters: + +```text +PubkeyAuthentication yes +PasswordAuthentication no +``` + +## Restart the SSH service + +```bash +sudo systemctl restart sshd +``` + +If it does not take effect, delete all files in `etc/ssh/sshd_config.d`. diff --git a/docs/en/tips/system/linux/swap.md b/docs/en/tips/system/linux/swap.md new file mode 100644 index 00000000..85ebe836 --- /dev/null +++ b/docs/en/tips/system/linux/swap.md @@ -0,0 +1,52 @@ +--- +title: Debian Configure Swap +author: Lee +--- + +## Create + +You can use `free -h` to check the current swap usage + +### Create a new swap file (set the size as needed) + +```bash +sudo fallocate -l 1G /swapfile +``` + +### Set file permissions to root only (optional) + +```bash +sudo chmod 600 /swapfile +``` + +### Format the file as swap space + +```bash +sudo mkswap /swapfile +``` + +### Enable swap + +```bash +sudo swapon /swapfile +``` + +### Enable automatic mounting + +Open the etc/fstab file and add at the end: + +```bash +/swapfile none swap sw 0 0 +``` + +## Modify + +### Change swap activation threshold + +Open etc/sysctl.conf and modify the value after `vm.swappiness=80`.If it does not exist, add a new line. + +### Change swap size + +- Use `swapoff -a` to turn off swap +- Delete the previously created `swapfile` +- Repeat the creation steps diff --git a/docs/en/tips/system/windows/index.md b/docs/en/tips/system/windows/index.md new file mode 100644 index 00000000..9c0c840d --- /dev/null +++ b/docs/en/tips/system/windows/index.md @@ -0,0 +1,8 @@ +--- +title: Windows +author: Lee +--- + +## Contents + + diff --git a/docs/en/tips/system/windows/wsl.md b/docs/en/tips/system/windows/wsl.md new file mode 100644 index 00000000..3352f48d --- /dev/null +++ b/docs/en/tips/system/windows/wsl.md @@ -0,0 +1,22 @@ +--- +title: Common WSL Commands +author: Lee +--- + +## Set Default User + +```bash +Debian config --default-user root +``` + +## Destroy System + +```bash +wsl --unregister Debian +``` + +## Create System + +```bash +wsl --install -d Debian +``` diff --git a/docs/tips/git/github-pr.md b/docs/tips/git/github-pr.md index 23008f02..fad3d33a 100644 --- a/docs/tips/git/github-pr.md +++ b/docs/tips/git/github-pr.md @@ -20,14 +20,14 @@ author: Lee 可以将分支更新到最新版本 (这两个按钮都有效，第一个为更新到最新版本并舍弃你本地仓库上的提交，第二个为更新到最新版本) -![](github-img/image11.png) +![](/tips/git/github-img/image11.png) ### 方案2 基于上游仓库开一个新的分支，在新的分支进行提交 -![](github-img/image12.png) -![](github-img/image13.png) +![](/tips/git/github-img/image12.png) +![](/tips/git/github-img/image13.png) ## 提交以后如何修改 @@ -37,8 +37,8 @@ PR 合并前分支和 PR 是绑定的，直接在对应分支修改即可。 进入 PR，点击 `Files changed` -![](github-img/image14.png) +![](/tips/git/github-img/image14.png) 点击 `Review changes` -![](github-img/image15.png) +![](/tips/git/github-img/image15.png) diff --git a/docs/tips/git/github.md b/docs/tips/git/github.md index 80819c80..806e3496 100644 --- a/docs/tips/git/github.md +++ b/docs/tips/git/github.md @@ -23,27 +23,27 @@ GitHub 官网: 打开首页，通过搜索栏找到想要做出贡献的仓库，也可以通过仓库链接直接跳转。 -![](github-img/image.png) +![](/tips/git/github-img/image.png) 在仓库代码页（首页），点击 Fork，复制仓库到你的账号下。 -![](github-img/image1.png) ![](github-img/image2.png) +![](/tips/git/github-img/image1.png) ![](/tips/git/github-img/image2.png) 进入你分叉出的仓库 -![](github-img/image3.png) +![](/tips/git/github-img/image3.png) 找到想要编辑的文件进行编辑，编辑后点击右上角保存。 -![](github-img/image4.png) ![](github-img/image5.png) +![](/tips/git/github-img/image4.png) ![](/tips/git/github-img/image5.png) 所有文件修改完毕后，返回仓库主页，并发起一个拉取请求。 -![](github-img/image6.png) ![](github-img/image7.png) +![](/tips/git/github-img/image6.png) ![](/tips/git/github-img/image7.png) 填写你的标题（必选）和 简介（可选），点击发送。 -![](github-img/image8.png) +![](/tips/git/github-img/image8.png) 等待上游仓库管理员合并你的拉取请求 @@ -61,11 +61,11 @@ GitHub 官网: 点击右上角你的头像，在弹出的侧边栏内选择 `Your repositories` -![](github-img/image9.png) +![](/tips/git/github-img/image9.png) 在页面内选择你想切换到的仓库 -![](github-img/image10.png) +![](/tips/git/github-img/image10.png) **注意：** diff --git a/docs/tips/gpgpu/trition-report.md b/docs/tips/gpgpu/trition-report.md index e5a814ff..6c296b29 100644 --- a/docs/tips/gpgpu/trition-report.md +++ b/docs/tips/gpgpu/trition-report.md @@ -28,8 +28,8 @@ import triton #### vecadd: BLOCK_SIZE = 16 -![](./images/trition-report/vector-add-performance-16.png) +![](/tips/gpgpu/images/trition-report/vector-add-performance-16.png) #### vecadd: BLOCK_SIZE = 32 -![](./images/trition-report/vector-add-performance-32.png) +![](/tips/gpgpu/images/trition-report/vector-add-performance-32.png) diff --git a/docs/tips/gpgpu/ventus-llvm-install.md b/docs/tips/gpgpu/ventus-llvm-install.md index f73a16ce..1337d4ca 100644 --- a/docs/tips/gpgpu/ventus-llvm-install.md +++ b/docs/tips/gpgpu/ventus-llvm-install.md @@ -52,7 +52,7 @@ cd J142/pocl/build/bin ./poclcc -l ``` -![](./images/llvm-img/poclcc.png) +![](/tips/gpgpu/images/llvm-img/poclcc.png) ## 运行测试用例 @@ -61,4 +61,4 @@ cd J142/pocl/build/examples/vecadd ./vecadd ``` -![](./images/llvm-img/vecadd.png) +![](/tips/gpgpu/images/llvm-img/vecadd.png) diff --git a/docs/tips/system/linux/gpg-sign.md b/docs/tips/system/linux/gpg-sign.md index 905821d6..acca9fe2 100644 --- a/docs/tips/system/linux/gpg-sign.md +++ b/docs/tips/system/linux/gpg-sign.md @@ -7,7 +7,7 @@ author: Lee 使用终端连接服务器，调 yubikey 内的 GPG 密钥签 Git 提交时提示错误，简要排查： -![](./pubilc/gpg-sign-img/gpg-sign-1.png) +![](/tips/system/linux/pubilc/gpg-sign-img/gpg-sign-1.png) 验证是否有有效私钥： @@ -15,7 +15,7 @@ author: Lee gpg --list-secret-keys --keyid-format LONG ``` -![](./pubilc/gpg-sign-img/gpg-sign-2.png) +![](/tips/system/linux/pubilc/gpg-sign-img/gpg-sign-2.png) 测试是否正确读取智能卡： @@ -23,7 +23,7 @@ gpg --list-secret-keys --keyid-format LONG gpg --card-status ``` -![](./pubilc/gpg-sign-img/gpg-sign-3.png) +![](/tips/system/linux/pubilc/gpg-sign-img/gpg-sign-3.png) 直接使用 GPG 测试签名： @@ -50,6 +50,6 @@ export GPG_TTY=$(tty) 重新测试签名： -![](./pubilc/gpg-sign-img/gpg-sign-4.png) +![](/tips/system/linux/pubilc/gpg-sign-img/gpg-sign-4.png) 成功弹出校验框，至此问题解决。 diff --git a/docs/tips/system/linux/ssh-agent.md b/docs/tips/system/linux/ssh-agent.md index f1f3358f..5ddb4b08 100644 --- a/docs/tips/system/linux/ssh-agent.md +++ b/docs/tips/system/linux/ssh-agent.md @@ -13,7 +13,7 @@ author: Lee 首先应确保本地ssh已正常运行，可使用 `ssh-add -l` 指令查询所有ssh密钥，也可运行 `ssh -T` 测试是否可以正确访问。 -![](./pubilc/ssh-agent-1.png) +![](/tips/system/linux/pubilc/ssh-agent-1.png) ### 设置 ssh agent forwarding